Script Kit 2.0 Release Candidate

[johnlindquist]

Script Kit 2.0 Release Candidate

Download for your platform from the releases page:
https://github.com/johnlindquist/kitapp/releases/tag/v1.99.82

New Main Menu

The main menu has been re-designed and optimized for your keyboard-centric workflows.

New Custom OSX Window

Prompts like editor and term which use ignoreBlur will now convert the window into an "app" window which can be accessed by cmd+tab, is pinned when switching spaces, and shows up in Mission Control. This is also forward-looking to v3 which I'll talk about more in the future...

Keywords

Borrowed directly from Alfred, keywords allow you to trigger a script by typing a keyword followed by a space.

A keyword can be a single character or a word. For example, c for clipboard.

Built-in Keywords

• s - Displays Snippets from your Snippets Directory
• c - Displays Clipboard History
• f - Find script by searching script contents
• kit - Access kit settings
• kenv - Access kenv options
• npm - Add/remove npm packages
• spell - List spelling suggestions for the input

And many others. To see them all, type keyword into the Script Kit prompt.

To create a custom keyword for your own scripts, add:

// Keyword: mycustomkeyword

If the first prompt is an await arg(), it will display the list in the main menu. Otherwise, it will jump to the next prompt.

Also, if the first prompt is a static list and you shave off the few milliseconds required to load the list from your script, you can cache the list (after the first run) by adding:

// Cache: true

Use caching sparingly, as it's only useful for // Keyword and // Shortcut where the first prompt is an arg with a static list.

Pass Main Menu Input to a Script

// Pass: true

The Pass metadata allows you to type into the main menu without your script being filtered out of the list. Once you select the script, the input you've typed will be "passed" into the script. You can access the "passed" input using flag?.pass. For example, if you want to pass the main menu input to the input of you first arg:

// Name: Pass Demo
// Pass: true

import "@johnlindquist/kit"

await arg({
  input: flag?.pass || "",
})

Pass "postfix"

Image you want to type: "How many moons does Jupiter have?" and have the "?" automatically trigger a script that reaches out to an AI service. You can do this by adding a "postfix" to the Pass metadata.

// Pass: ?

This will automatically trigger the script when you type a "?" at the end in the main menu and the entire input will be passed to the script as flag?.pass.

Multi-select Prompt await select()

let arrayOfChoices = await select("Pick one or more", ["one", "two", "three"])

Probably the most requested feature, Script Kit now has a select prompt which allows you to pick multiple choices.

Themes Per Light/Dark Mode

You can now customize which theme will be active for both light and dark more or use the same theme for both.

Snippets Directory

In your ~/.kenv/snippets directory, create .txt files you want to use as snippets. For example:

1. Create ~/.kenv/snippets/lorem.txt
2. Add the following text to the file:

// Name: Lorem Ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

The "Lorem Ipsum" snippet will now appear in the Snippets menu using the s keyword. Select the snippet will paste it into the current application.

Adding Snippet metadata will allow you to invoke the snippet anywhere on your system. It's a best practice to use a "postfix", such as ",,", to avoid triggering the snippet when you don't want to.

// Snippet: lorem,,

Snippet Creator

Typing ns from the main menu will launch the quick snippet creator. There's a helpful guide there that will show all the available options. Just to list a few:

• Tab stops: $0, $1, $2, $3
• Dropdown list: ${|apple,banana,cherry|}
• Current selection: $SELECTION
• Clipboard content: $CLIPBOARD

and many more...

If you need more advanced scenarios, for example clipboard history:

let history = await getClipboardHistory()
let text = await arg("Pick an item from your history", history.map(item => item.value)

let result = await template(`Hello $0,

${text}
`)

await writeFile(home("example.txt"), result)

Actions

The new actions array makes it much easier to assign shortcuts and behaviors when you have a choice selected. You can access the actions menu by pressing righton the keyboard, then quickly search to execute the action you want to take with the currently focused choice:

// Name: Actions Example

import { Action } from "@johnlindquist/kit"

// Using a "flag" determines where to do to custom logic: After the prompt or in the action
// Also, "flags" are supported when running the script in the terminal with `--js`
let actions: Action[] = [
  {
    shortcut: `${cmd}+t`,
    name: "Append .ts",
    visible: true, // Display shortcut in the prompt
    onAction: async (input, state) => {
      // Since we're not using a "flag", we can do custom logic here
      submit(`${state.focused?.name}.ts`)
    },
  },
  {
    name: "Append .js",
    flag: "js", // Set `global.flag.js` to true when selecting the action
  },
]

let result = await arg("Pick a number", ["one", "two", "three"], actions)

if (flag.js) {
  result = `${result}.js`
}

inspect(result)

Previews on All Prompts

You can build-out helpful previews on the right side for all prompts now (see the Snippet Creator above for a great example). This is especially useful for prompts like editor, drop, and term where you may need reminders on what the script is doing or steps you want to guide the user through.

await editor({
  value: `Book Outline`,
  preview: md(`# Requirements
- Cover Major Characters
- Address the theme
- Have a beginning, middle, and end  
  `),
})

Move kenv to a Different Directory

Type kit move into the main prompt to move your kenv directory to a different location. This is useful if you want to keep your scripts in dotfiles or other setup.

onClick and onKeydown Globals

• Global event handlers for click and type events.

Custom TypeScript Loader

The new custom loader eliminates the need to watch .ts files for changes (which caused many issues from a long-running app). We now have a customized loader that can run any TypeScript file instantly.

An awesome benefit of this is you can create a script anywhere on your system, such as ~/Desktop/my-script.ts (or js if you prefer) and run it from script runner: ~/.kit/bin/kit ~/Desktop/my-script.ts.

Note: Your IDE won't recognize the import statements since it's not in a project, but the script will run just fine.

If we get enough requests, we will allow you to run the scripts from the built-in file browser through the app as well.

Watch Scripts for npm Install

As you're writing your scripts in your favorite editor, Kit.app will detect if you've added a new npm package and automatically prompt you to install it using the Kit.app built-in terminal.

Road to v2

The plan is to release v2 in mid-December. I'll be focusing on updating documentation, guides, tips, and tricks to finally help everyone get a more complete grasp of what Script Kit is capable of. There are a few more APIs which haven't been announced which will be included as well.

Questions?

Please ask below. We're always happy to help figure out better workflows to optimize your day. Happy scripting!

- John

[josephcrawfordSRH]

@johnlindquist I upgraded to this and it would not allow my script to work any longer, the async function that returned an array to the arg method would no longer allow me to search. I quickly went to the site and downloaded the older version I had and once installed everything seems to have broken.

I thought that using AppZapper to remove all associated files and removing my .kenv/ directory would have solved this but even after a reinstall that is not happening. Upon first open I get a t.map is not a function call.

[johnlindquist]

@josephcrawfordSRH any chance you can post a screen recording so I'm absolutely clear of the behavior?

[johnlindquist]

@josephcrawfordSRH I believe I see what's going on:

Using a function with arg implies that you want to implement your own custom searching/generation logic. Typically, that would look like this:

let choices = ["apple", "banana", "orange"]
await arg("Type something", async (input)=> {
return choices.filter(c => c.includes(input)) //custom searching/generation logic based on input
})

This function will run every time a key is pressed. So the logic in your script is running find/fetch with every key press, even though it's not changing based on input.

bug

2.0 refactored the searching/scoring logic. There's now a check if there's no input argument, it only run the first pass, then switches to a noop. This is causing the list to clear when you type. I'll re-implement a "run every time, even if no input", but...

solution

I strongly recommend refactoring by hoisting the async functions outside of your args then call them before the arg runs:

let getAllBranches = async ()=> { // branches logic } // just copy/paste the async function
let branches = await getAllBranches()
let branch =await arg("Which branch?", branches)

// Also do the same with the "projects" logic

Please let me know if something's not clear.

Also

I recommend using cwd inside the exec options, instead of cd:

let result = await exec(`ls`, {
  cwd: home("dev"),
})

inspect(result.stdout)

It helps avoid accidentally running commands in the wrong directly if you ever refactor of if cd is called somewhere else in your script.

[josephcrawfordSRH]

Awesome thanks for the feedback I will see what I can work out later this evening or tomorrow evening. I appreciate your ability to respond so quickly.

[josephcrawfordSRH]

@johnlindquist I refactored the code quite a bit last night and upgraded to v2 as suggested. Things are working somewhat smooth but when refactoring to use your cwd suggestion things are not quite working.

async function fetchBranchesFromServer(project) {
  let projectDir = await getProjectDirectory();
  console.log(`${projectDir}/${project}`); // this is a path /Users/username/projects/project which is a git repo

  // These were originally combined with `git fetch --all && git branch -a` but it was failing so i figured i would try to separate them.
  await exec(`git fetch`, {
   cwd: `${projectDir}/${project}`, 
  });

  const branchString = await exec(`git branch -a`, {
    cwd: `${projectDir}/${project}`,
  });

  let branches = branchString.stdout.split("\n");
  branches = branches.filter((b) => {
    return b !== "" && !b.includes("dependabot") &&
      !b.includes("HEAD ->") && !b.includes("* ") &&
      !branches.includes(b.replace("remotes/origin/", "").trim())
  }).map((b) => {
    return b.replace("remotes/origin/", "").trim();
  });

  return [...branches];
}

Command failed with exit code 128: git symbolic-ref --short HEAD
fatal: not a git repository (or any of the parent directories): .git
Error: Command failed with exit code 128: git symbolic-ref --short HEAD
fatal: not a git repository (or any of the parent directories): .git
    at makeError (file:///Users/josephcrawford/.kit/node_modules/@johnlindquist/globals/dist/index.js:36:111645)
    at file:///Users/josephcrawford/.kit/node_modules/@johnlindquist/globals/dist/index.js:36:127769
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)

I have verified that the ${projectDir}/${project} does in-fact point to the project directory that is a git repo.

When the git commands were combined, this is the error that I was getting

Command failed with exit code 128: git fetch && git branch -a
fatal: '&&' does not appear to be a git repository
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
Error: Command failed with exit code 128: git fetch && git branch -a
fatal: '&&' does not appear to be a git repository
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
    at makeError (file:///Users/josephcrawford/.kit/node_modules/@johnlindquist/globals/dist/index.js:36:111645)
    at file:///Users/josephcrawford/.kit/node_modules/@johnlindquist/globals/dist/index.js:36:127769
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)

[josephcrawfordSRH]

@johnlindquist This is the full source

// Exclude: true

import "@johnlindquist/kit";

export async function opob(newWindow = false) {
  let editor = await getCodeEditor();

  const projectDir = await getProjectDirectory();
  const projects = await getProjects();

  const project = await arg("Which project?", projects);
  const projectPath = `${projectDir}/${project}`;

  const branches = await getAllProjectBranches(project);
  const branch = await arg("Which branch?", branches);

  let windowFlag = "-r";
  if (newWindow) {
    windowFlag = "-n";
  }

  let changes = await exec(`git diff --name-only`, {
    cwd: projectPath,
  });

  if (changes && branch !== await getCurrentBranch()) {
    if (
      await arg("You have changed files, do you want to stash them?", [
        "Yes",
        "No",
      ]) === "Yes"
    ) {
      await exec(`git stash push -m "OPOB Stash"`, {
        cwd: projectPath,
      });
      changes = false;
    }
  }

  if (!changes) {
    await exec(`git checkout ${branch}"`, {
      cwd: projectPath,
    });
  }

  await exec(`${editor} ${windowFlag} ${projectPath}`);
}

const cyrb53 = (str, seed = 0) => {
  let h1 = 0xdeadbeef ^ seed, h2 = 0x41c6ce57 ^ seed;
  for (let i = 0, ch; i < str.length; i++) {
    ch = str.charCodeAt(i);
    h1 = Math.imul(h1 ^ ch, 2654435761);
    h2 = Math.imul(h2 ^ ch, 1597334677);
  }
  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);

  return 4294967296 * (2097151 & h2) + (h1 >>> 0);
};

const OPOB_CACHE_FILE = kenvPath('cache/opob.json');

async function readCache() {
  return JSON.parse(await ensureReadFile(OPOB_CACHE_FILE, "{}"));
}

async function writeCache(cache) {
  await writeFile(OPOB_CACHE_FILE, JSON.stringify(cache));
}

async function getCacheKey(key) {
  const cache = await readCache();
  return cache[key] ?? null;
}

async function setCacheKey(key, value) {
  let cache = await readCache();
  cache[key] = value;
  await writeCache(cache);
}

async function getCodeEditor() {
  let editor = await getCacheKey('editor');
  if (!editor) {
    let editors = [];

    const which = await exec(`which code-insiders || which code`);
    if (which.stdout.includes("/code-insiders")) {
      editors.push("code-insiders");
    }

    if (which.stdout.includes("/code")) {
      editors.push("code");
    }

    if (editors.length > 1) {
      editor = await arg("Which Editor?", editors);
      if (await arg("Remember Editor?", ["Yes", "No"]) === 'Yes') {
        // cache the code they wish to use.
        setCacheKey('editor', editor);
      }
    }

    if(editors.length === 1) {
      editor = editors[0];
    }

    if (editors.length === 0) {
      let message = md(`# And Editor was not found
    Please install an editor CLI such as code, code-insiders or phpstorm
      `)
      await div(message);
      exit(1);
    }
  }

  return editor;
}

async function getProjects() {
    let projects = await getCacheKey('projects');
    if (!projects) {
      const p = await exec(
        `find -L ${projectDir} -maxdepth 4 -name .git -type d -prune`,
      );
      const pList = p.stdout.split("\n");
    
      projects = pList.map((project) => {
        return project.replace(projectDir + "/", "").replace("/.git", "");
      });

      await setCacheKey('projects', projects);
    }

    return projects;  
}

async function getAllProjectBranches(project) {
  let branches = getCacheKey('branches') || {};
  let projectHash = cyrb53(project);

  if (!branches[projectHash]) {
    branches[projectHash] = await fetchBranchesFromServer(project);
    await setCacheKey('branches', branches);
  }

  return currentBranchFirst(branches[projectHash]);
}

async function fetchBranchesFromServer(project) {
  let projectDir = await getProjectDirectory();
  console.log(`${projectDir}/${project}`);
  
  await exec(`cd ${projectDir}/${project}`, {
    cwd: home()
  });

  const branchString = await exec(`git fetch && git branch -a`, {
    cwd: `${projectDir}/${project}`,
  });

  let branches = branchString.stdout.split("\n");
  branches = branches.filter((b) => {
    return b !== "" && !b.includes("dependabot") &&
      !b.includes("HEAD ->") && !b.includes("* ") &&
      !branches.includes(b.replace("remotes/origin/", "").trim())
  }).map((b) => {
    return b.replace("remotes/origin/", "").trim();
  });

  return [...branches];
}

async function getCurrentBranch() {
  const current = await exec(`git symbolic-ref --short HEAD`);
  return current.stdout.trim();
}

async function currentBranchFirst(branches) {
  const currentBranch = await getCurrentBranch();

  const filteredBranches = branches.filter(b => b !== currentBranch);

  return [currentBranch, ...filteredBranches];
}

async function getProjectDirectory() {
  let projectDir = await getCacheKey('projectDir');

  if (!projectDir) {
    projectDir = await path(home());
  }

  setCacheKey('projectDir', projectDir);

  return projectDir;
}

[srhyne]

Bravo @johnlindquist! The new format for actions is fantastic! I struggled a bit before to get the -> right arrow to enable showing of flags. Now it works flawlessly.

The design refresh is really great too!