Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor CLI linking process and update documentation

konstantin-paulus2e1ccb14f908
diff --git a/README.md b/README.md
index 0749824f..0f9fdf7e 100644
--- a/README.md
+++ b/README.md
@@ -243,13 +243,13 @@ cp apps/web/.env.example apps/web/.env # required: the app won't run without i
npm run dev
```
-To put `dapi` on your PATH (macOS/Homebrew layout; adjust the link target for other setups), link it once:
+To put `dapi` on your PATH, link it once (`unlink` undoes it):
```sh
-npm run symlink:create --workspace=@diffusionstudio/cli
+npm run link --workspace=@diffusionstudio/cli
```
-The link points at the CLI build, which `npm run dev:desktop` refreshes on every start, so the linked `dapi` always runs the latest code.
+The link points at the CLI build, which `npm run dev:desktop` refreshes on every start, so the linked `dapi` always runs the latest code. On macOS it is a symlink in Homebrew's bin; on Windows it is `%LOCALAPPDATA%\DiffusionStudio\bin\dapi.cmd`, and that folder needs to be on your PATH.
Before sending a PR:
diff --git a/apps/cli/package.json b/apps/cli/package.json
index c92546a8..3d81ef27 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -9,10 +9,8 @@
"scripts": {
"build": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/index.js && node -e \"process.platform !== 'win32' && require('node:fs').chmodSync('dist/index.js', 0o755)\"",
"check": "tsc --noEmit",
- "symlink:remove": "rm -f /opt/homebrew/bin/dapi",
- "symlink:create": "npm run build && ln -sf \"$PWD/dist/index.js\" /opt/homebrew/bin/dapi",
- "shim:create": "npm run build && node scripts/dev-shim.mjs",
- "shim:remove": "node scripts/dev-shim.mjs --remove"
+ "link": "npm run build && node scripts/dev-link.mjs",
+ "unlink": "node scripts/dev-link.mjs --remove"
},
"dependencies": {
"@diffusionstudio/dapi": "*",
diff --git a/apps/cli/scripts/dev-link.mjs b/apps/cli/scripts/dev-link.mjs
new file mode 100644
index 00000000..1fce671e
--- /dev/null
+++ b/apps/cli/scripts/dev-link.mjs
@@ -0,0 +1,74 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+// Puts a `dapi` on the PATH that runs this workspace's build, for developing
+// against the CLI. `npm run dev:desktop` rebuilds the CLI on every start, so
+// the link keeps running the latest code. Where it goes is where a dev build
+// of the desktop app looks for the binary it registers with agents and
+// reports in the settings CLI card (apps/desktop/src/cli-install.ts and
+// mcp-install.ts):
+//
+// macOS a symlink in Homebrew's bin, `/opt/homebrew/bin/dapi`, which is
+// user-writable, so no admin prompt. The packaged app uses
+// `/usr/local/bin` instead and the two never collide.
+// Windows `%LOCALAPPDATA%\DiffusionStudio\bin\dapi.cmd`, the same file the
+// packaged app keeps its own shim in (apps/desktop/src/cli-windows.ts).
+// A packaged app rewrites it on launch, so run this again after
+// using one. The folder has to be on PATH; the packaged app's
+// "Install CLI" does that, or add it by hand.
+//
+// node scripts/dev-link.mjs create the link
+// node scripts/dev-link.mjs --remove delete it
+
+import { existsSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const script = join(dirname(fileURLToPath(import.meta.url)), "..", "dist", "index.js");
+const remove = process.argv.includes("--remove");
+
+if (process.platform === "win32") {
+ const local = process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local");
+ const dir = join(local, "DiffusionStudio", "bin");
+ const shim = join(dir, "dapi.cmd");
+
+ if (remove) {
+ rmSync(shim, { force: true });
+ console.log(`dev-link: removed ${shim}`);
+ process.exit(0);
+ }
+
+ const batch = (path) => path.replaceAll("%", "%%");
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(shim, ["@echo off", "setlocal", `node "${batch(script)}" %*`, ""].join("\r\n"));
+ console.log(`dev-link: ${shim} -> ${script}`);
+
+ const onPath = (process.env.PATH ?? "")
+ .split(";")
+ .some((entry) => win32.normalize(entry).replace(/\\+$/, "").toLowerCase() === dir.toLowerCase());
+ if (!onPath) console.log(`dev-link: add ${dir} to your PATH to run \`dapi\` from a terminal.`);
+} else if (process.platform === "darwin") {
+ const dir = "/opt/homebrew/bin";
+ const link = join(dir, "dapi");
+
+ if (remove) {
+ rmSync(link, { force: true });
+ console.log(`dev-link: removed ${link}`);
+ process.exit(0);
+ }
+
+ if (!existsSync(dir)) {
+ console.error(`dev-link: ${dir} does not exist (Homebrew is not installed, or is an Intel install); ` +
+ `the dev build of the app only recognises a link there.`);
+ process.exit(1);
+ }
+
+ rmSync(link, { force: true });
+ symlinkSync(script, link);
+ console.log(`dev-link: ${link} -> ${script}`);
+} else {
+ console.error(`dev-link: no link location for ${process.platform}; put ${script} on your PATH yourself.`);
+ process.exit(1);
+}
diff --git a/apps/cli/scripts/dev-shim.mjs b/apps/cli/scripts/dev-shim.mjs
deleted file mode 100644
index abd1c234..00000000
--- a/apps/cli/scripts/dev-shim.mjs
+++ /dev/null
@@ -1,45 +0,0 @@
-/* This Source Code Form is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-
-// Windows counterpart of `symlink:create`: points the `dapi` shim at this
-// workspace's build, run on the system's Node. It goes where the packaged app
-// keeps its own shim (apps/desktop/src/cli-windows.ts), which is also where a
-// dev build of the app looks for the binary it registers with agents. The two
-// share the file: a packaged app rewrites it on launch, so run this again
-// after using one.
-//
-// node scripts/dev-shim.mjs write the shim
-// node scripts/dev-shim.mjs --remove delete it
-
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, win32 } from "node:path";
-import { fileURLToPath } from "node:url";
-
-if (process.platform !== "win32") {
- console.error("dev-shim is for Windows; use `npm run symlink:create` on macOS.");
- process.exit(1);
-}
-
-const local = process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local");
-const dir = join(local, "DiffusionStudio", "bin");
-const shim = join(dir, "dapi.cmd");
-
-if (process.argv.includes("--remove")) {
- rmSync(shim, { force: true });
- console.log(`dev-shim: removed ${shim}`);
- process.exit(0);
-}
-
-const script = join(dirname(fileURLToPath(import.meta.url)), "..", "dist", "index.js");
-const batch = (path) => path.replaceAll("%", "%%");
-
-mkdirSync(dir, { recursive: true });
-writeFileSync(shim, ["@echo off", "setlocal", `node "${batch(script)}" %*`, ""].join("\r\n"));
-console.log(`dev-shim: ${shim} -> ${script}`);
-
-const onPath = (process.env.PATH ?? "")
- .split(";")
- .some((entry) => win32.normalize(entry).replace(/\\+$/, "").toLowerCase() === dir.toLowerCase());
-if (!onPath) console.log(`dev-shim: add ${dir} to your PATH to run \`dapi\` from a terminal.`);
diff --git a/apps/desktop/WINDOWS.md b/apps/desktop/WINDOWS.md
index 9494f851..0ce34e80 100644
--- a/apps/desktop/WINDOWS.md
+++ b/apps/desktop/WINDOWS.md
@@ -403,8 +403,10 @@ Goal: developing on a Windows machine is as easy as on macOS, and the app
gets the Windows 11 look.
Status: task 1 runs on Windows: the dev build starts through
-`scripts/dev-desktop.mjs` (2026-09-21). Task 2 (`npm run shim:create` in
-`apps/cli`) is implemented but not yet confirmed on Windows. Task 3 (Mica) was
+`scripts/dev-desktop.mjs` (2026-09-21). Task 2 is implemented but not yet
+confirmed on Windows; the script is `npm run link` in `apps/cli`
+(`scripts/dev-link.mjs`), one command on both platforms, which writes the
+Homebrew symlink on macOS and the `dapi.cmd` shim on Windows. Task 3 (Mica) was
tried and dropped, see below. Tasks 4 and 5 are open.
Mica, tried on Windows on 2026-09-21 and reverted: the window stays solid.
@@ -428,9 +430,9 @@ Tasks:
-ano` for the port, `wmic`/`Get-Process` for the command line, and
`taskkill /T /F` for teardown. Spawn `.cmd` tool shims with `shell: true`.
2. **Dev shim**: `apps/cli/package.json` `symlink:create` links into
- Homebrew. Add a `shim:create` script that writes a `dapi.cmd` into the
- stable shim folder pointing at the workspace build, and teach
- `mcp-install.ts`'s dev binary to use it.
+ Homebrew. Add a script that writes a `dapi.cmd` into the stable shim
+ folder pointing at the workspace build, and teach `mcp-install.ts`'s dev
+ binary to use it.
3. **Mica** (`main.ts`): on Windows 11 22H2+, `backgroundMaterial: "mica"`
with a transparent `backgroundColor` gives the vibrancy look. Electron has
had bugs combining this with `titleBarOverlay`; treat as optional and
diff --git a/apps/desktop/src/cli-install.ts b/apps/desktop/src/cli-install.ts
index d2d5ddc6..0ee9d95c 100644
--- a/apps/desktop/src/cli-install.ts
+++ b/apps/desktop/src/cli-install.ts
@@ -14,7 +14,7 @@ import type { CliInstallResult, CliStatus, CliUninstallResult } from "./main-cha
export const CLI_LINK_PATH = "/usr/local/bin/dapi";
// The dev workflow links the workspace build into Homebrew's bin instead
-// (`symlink:create` in apps/cli), so that location counts as installed too.
+// (`npm run link` in apps/cli), so that location counts as installed too.
const DEV_LINK_PATH = "/opt/homebrew/bin/dapi";
/**
@@ -103,7 +103,7 @@ export async function installCli(): Promise<CliInstallResult> {
if (!app.isPackaged) {
return {
status: "error",
- error: `Installing the CLI is only available in the packaged app. Use \`npm run ${process.platform === "win32" ? "shim:create" : "symlink:create"}\` in development.`,
+ error: `Installing the CLI is only available in the packaged app. Use \`npm run link\` in apps/cli in development.`,
};
}
if (process.platform === "win32") return installCliWin32();
diff --git a/apps/desktop/src/main-channels.ts b/apps/desktop/src/main-channels.ts
index fd2de15e..4bf0230a 100644
--- a/apps/desktop/src/main-channels.ts
+++ b/apps/desktop/src/main-channels.ts
@@ -140,7 +140,7 @@ export type McpApplyResult = {
// Where the `dapi` command stands. `managed` means what is there is a
// symlink (the app's own, or the dev workflow's Homebrew link), which
// "Uninstall" can remove; `available` that this build can create the app's
-// link (a dev build cannot: that is `npm run symlink:create`).
+// link (a dev build cannot: that is `npm run link` in apps/cli).
export type CliStatus = {
installed: boolean;
path: string | null;
diff --git a/apps/desktop/src/mcp-install.ts b/apps/desktop/src/mcp-install.ts
index 16fb2dae..f5cac9e2 100644
--- a/apps/desktop/src/mcp-install.ts
+++ b/apps/desktop/src/mcp-install.ts
@@ -29,7 +29,7 @@ import type { AgentPath, AgentTarget, McpServerSpec } from "./mcp-config";
import type { McpAgentStatus, McpApplyRequest, McpApplyResult, McpStatus } from "./main-channels";
// The dev workflow links the workspace build into Homebrew's bin
-// (`symlink:create` in apps/cli); that is the binary a dev build registers.
+// (`npm run link` in apps/cli); that is the binary a dev build registers.
const DEV_BINARY = "/opt/homebrew/bin/dapi";
/**
diff --git a/scripts/dev-desktop.mjs b/scripts/dev-desktop.mjs
index 727e1cd3..86678956 100644
--- a/scripts/dev-desktop.mjs
+++ b/scripts/dev-desktop.mjs
@@ -3,7 +3,7 @@
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
// One command to develop the desktop app from source. It:
-// 1. builds the CLI, so a linked `dapi` (see symlink:create) runs the
+// 1. builds the CLI, so a linked `dapi` (see `npm run link` in apps/cli) runs the
// latest code and the app's headless server matches it;
// 2. starts the web dev server (Vite on :5173), first reclaiming the port
// from a Vite left behind by an earlier run that did not come down;