@chatcut/cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# ChatCut CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The small command-line entry point for the official ChatCut Desktop app. It
+contains no video editor, second MCP server, downloaded skills catalog, or
+third-party runtime dependencies. Desktop owns editing, agent connections and
+the skills shipped with that app version.
+
+The `connect` entry point requires `@chatcut/cli` 0.1.1 or later. Merging source
+changes alone does not publish a new npm version.
+
+```sh
+npx --yes @chatcut/cli app
+
+# Optional permanent command:
+npm install --global @chatcut/cli
+chatcut
+chatcut app
+```
+
+Node.js 22+ is required. Desktop supports macOS 13+ on Apple Silicon or Intel and
+Windows x64. This launcher does not install a GUI on Linux or a headless server.
+
+`chatcut` and `chatcut app` reuse an installed, signed production app. When it is
+missing, they download the official artifact, validate its publisher, install it
+for the current user when necessary, and request launch. Repeated calls preserve
+the existing app, account and projects. Failed launch never triggers replacement.
+macOS copies use a new staging bundle and rollback rather than merging bundles.
+Windows uses the signed per-user NSIS installer. OS policy, missing privileges,
+and signature assessment failures retain their original evidence.
+
+```sh
+chatcut connect --json
+chatcut connect --client codex --json
+chatcut connect --client claude-code --json
+chatcut doctor --json
+chatcut doctor --client codex --json
+chatcut doctor --fix --json
+chatcut update --json
+```
+
+`connect` is the agent setup entry point. It opens/installs Desktop, asks Desktop
+to register or repair the supported agent integrations and sync its managed
+skills, then verifies the local MCP connection with a real tool call. Tools are
+provided over Desktop's MCP server. Use `--client` to select Codex or Claude Code;
+without it, both supported integrations are considered. The command reuses
+`doctor --fix`, including its standing opt-outs and preservation of custom skills.
+Read the returned findings for skipped hosts or remaining actions; passing checks
+does not mean an opted-out or unavailable host was connected. Start a new agent
+conversation after connection or skill changes to load the current tools and skills.
+JSON results identify this entry point with `command: "connect"`.
+
+Doctor without `--fix` does not install or open Desktop or change agent settings.
+It inspects a running Desktop through its authenticated user-scoped IPC, then
+starts a fresh local MCP client, negotiates the protocol, lists tools and calls
+`get_active_project`. An empty active project is valid. A cached list followed by
+a failed tool call is a failed check. Desktop may serve MCP reads while its GUI
+is closed; a working MCP probe does not establish that the GUI is running or that
+the current host conversation has loaded its tools and skills.
+
+`--fix` explicitly opens/installs Desktop, asks Desktop to repair the selected
+supported integration(s), and checks the result. Desktop continues to own host
+configuration and skill synchronization, including its standing opt-outs.
+Unchanged manifest-owned obsolete skills can be removed. User-edited, foreign,
+symlinked and ambiguous overlapping skills are preserved and reported. Different
+client variants are intentional and must not be deduplicated by name alone.
+
+Doctor reports original errors and remaining actions. Sign in within Desktop
+when needed; start a new agent conversation after its connection or skill set
+changes. A fresh diagnostic client cannot prove the current host's discovery
+state. Older Desktop releases without the doctor IPC report an update requirement.
+
+When a host CLI fails, Desktop reports its source error code and operation stage
+and marks omitted command output explicitly. Inspect that host locally for the
+remaining error text; an omitted message is an evidence gap, not a diagnosis.
+
+`update` is explicit and separate from diagnosis. Close Desktop first; it never
+forces a running editor to quit. It uses the official signed release, preserves
+user data and refuses downgrades. Shared Windows installations use their existing
+app updater or an interactive official installer.
+
+`--json` writes one JSON result to stdout; progress goes to stderr. Exit 0 means
+the requested operation completed or all required diagnostic checks passed.
+Exit 1 retains the failing stage, original cause and remaining action. Informative
+opt-outs, unavailable optional hosts and preserved custom skills are not failures.
+
+The historical `@chatcut/skill` package also exports a `chatcut` executable for its
+cloud job workflow. Use `npx --yes @chatcut/cli ...` without changing that install,
+or explicitly remove the old global package before installing this one globally.
+Do not use `--force` to overwrite another package's executable. Its saved cloud
+credentials and jobs are not migrated or deleted by this CLI.
+
+For contributors: run `npm test` and `npm pack --dry-run` from this directory.
+Native install/trust boundaries have deterministic fixtures on macOS, Windows
+and Linux CI; actual publisher validation and a real installation remain separate
+release acceptance evidence. Publish with the organization's npm release identity
+after review, inspect the tarball, and verify the published `npx` entry point on a
+clean supported machine before advertising availability.

package/bin/chatcut.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.mjs";
+
+process.exitCode = await runCli(process.argv.slice(2));

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@chatcut/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Install, open, diagnose and repair ChatCut Desktop",
+  "license": "UNLICENSED",
+  "bin": {
+    "chatcut": "bin/chatcut.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "check-types": "node --check bin/chatcut.mjs && node --check src/cli.mjs && node --check src/doctor.mjs && node --check src/rpc.mjs && node --check src/desktop.mjs",
+    "lint": "oxlint src bin tests",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,116 @@
+import { parseArgs } from "node:util";
+
+import packageInfo from "../package.json" with { type: "json" };
+import { ensureDesktop, updateDesktop } from "./desktop.mjs";
+import { errorEvidence, runDoctor } from "./doctor.mjs";
+
+const HELP = `ChatCut — your desktop video editor
+
+Usage:
+  chatcut                         Open Desktop; install it if needed
+  chatcut app                     Same as chatcut
+  chatcut connect [--json]         Open Desktop, connect agents and sync skills
+  chatcut doctor [--json]          Check Desktop, MCP and managed skills
+  chatcut doctor --fix [--json]    Repair supported connection and skill issues
+  chatcut update [--json]          Update Desktop after closing it
+
+Options:
+  --client codex|claude-code       Limit connect or doctor to one integration
+  --json                          Write one structured result to stdout
+  --help                          Show help without opening Desktop
+  --version                       Show CLI version
+
+First use: npx --yes @chatcut/cli app
+Desktop supports macOS 13+ and Windows x64. Node.js 22+ is required for this CLI.
+`;
+
+export async function runCli(args, dependencies = {}) {
+  const stdout = dependencies.stdout ?? process.stdout;
+  const stderr = dependencies.stderr ?? process.stderr;
+  let json = args.includes("--json");
+  try {
+    const { positionals, values } = parseArgs({
+      allowPositionals: true,
+      args,
+      options: {
+        client: { type: "string" },
+        fix: { type: "boolean" },
+        help: { short: "h", type: "boolean" },
+        json: { type: "boolean" },
+        version: { short: "v", type: "boolean" },
+      },
+    });
+    json = !!values.json;
+    if (values.help || positionals[0] === "help") {
+      stdout.write(HELP);
+      return 0;
+    }
+    if (values.version) {
+      stdout.write(`${packageInfo.version}\n`);
+      return 0;
+    }
+    const command = positionals[0] ?? "app";
+    if (
+      positionals.length > 1 ||
+      !["app", "connect", "doctor", "update"].includes(command)
+    )
+      throw new Error("Unknown command. Run chatcut --help.");
+    if (values.fix && command !== "doctor")
+      throw new Error("--fix applies only to chatcut doctor.");
+    if (values.client && !["connect", "doctor"].includes(command))
+      throw new Error("--client applies only to chatcut connect or doctor.");
+    if (values.client && !["claude-code", "codex"].includes(values.client))
+      throw new Error("--client must be codex or claude-code.");
+    const options = {
+      onProgress: (entry) =>
+        stderr.write(`${typeof entry === "string" ? entry : entry.message}\n`),
+    };
+    let result;
+    if (command === "doctor" || command === "connect") {
+      result = await (dependencies.doctor ?? runDoctor)({
+        ...options,
+        client: values.client,
+        fix: command === "connect" || !!values.fix,
+      });
+      result = { ...result, command };
+    } else {
+      const desktop = await (
+        command === "app"
+          ? (dependencies.ensure ?? ensureDesktop)
+          : (dependencies.update ?? updateDesktop)
+      )(options);
+      result = { command, desktop, ok: true, schemaVersion: 1 };
+    }
+    if (json) stdout.write(`${JSON.stringify(result)}\n`);
+    else if (command === "doctor" || command === "connect") {
+      stdout.write(
+        command === "connect"
+          ? `ChatCut Connect: ${result.ok ? "checks passed" : "issues found"}\n`
+          : `ChatCut Doctor: ${result.ok ? "healthy" : "issues found"}\n`,
+      );
+      for (const check of result.checks)
+        stdout.write(
+          `${check.status === "pass" ? "OK" : "FAIL"}  ${check.message}${check.error ? ` ${check.error.message ?? check.error}` : ""}\n`,
+        );
+      for (const finding of result.findings)
+        stdout.write(`INFO  ${finding.message}\n`);
+      for (const change of result.repair?.changes ?? [])
+        stdout.write(`FIXED  ${change}\n`);
+      if (!result.ok)
+        stdout.write(
+          "Run chatcut doctor --fix for supported repairs. Sign-in and agent-session reloads may still be needed.\n",
+        );
+    } else
+      stdout.write(
+        command === "app"
+          ? "ChatCut launch requested. Run chatcut doctor to check the agent connection.\n"
+          : `ChatCut Desktop: ${result.desktop.action}.\n`,
+      );
+    return result.ok ? 0 : 1;
+  } catch (error) {
+    const result = { error: errorEvidence(error), ok: false, schemaVersion: 1 };
+    if (json) stdout.write(`${JSON.stringify(result)}\n`);
+    else stderr.write(`ChatCut: ${result.error.message}\n`);
+    return 1;
+  }
+}