@easonwumac/computer-linker 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to Computer Linker will be documented in this file.
 This project follows a small pre-1.0 changelog: breaking contract changes are
 called out even when the package version is still `0.x`.
 
+## 0.1.5 - 2026-06-27
+
+### Changed
+
+- `quickstart --json` now exposes `commands.check` as the productized install
+  check command while preserving `commands.selfTest` as a compatibility alias
+  for older agents.
+- README and release/manual test docs now use `computer-linker check` as the
+  primary isolated install check command.
+
+## 0.1.4 - 2026-06-27
+
+### Added
+
+- Added `computer-linker check` as the productized install check command. It
+  runs the existing isolated self-test flow while keeping `self-test` as a
+  compatibility/advanced command.
+
 ## 0.1.3 - 2026-06-27
 
 ### Added

package/README.md

@@ -16,10 +16,11 @@ computer; Cloudflare, Tailscale, or OpenAI tunnel exposure is optional.
 
 Install the CLI, expose one folder, and keep the server running:
 
-```powershell
-npm install -g @easonwumac/computer-linker
-computer-linker start C:\Projects\my-app
-```
+```powershell
+npm install -g @easonwumac/computer-linker
+computer-linker check
+computer-linker start C:\Projects\my-app
+```
 
 Leave that terminal running. In another terminal, copy the MCP client settings
 and verify the connection:
@@ -65,14 +66,18 @@ File content reads and text searches block common sensitive files by default,
 including `.env*`, private keys, credential JSON files, and cloud CLI credential
 directories. Keep real secrets outside exposed folders.
 
-`self-test` is safe to run before exposing real folders. It creates a temporary
-config and workspace, starts a loopback HTTP MCP server, verifies `/healthz`,
-the local JSON API, MCP initialize, tools/list, `get_computer_info`, and one
-read-only `computer_operation`, then removes the temporary files.
-
-There is no web dashboard in the product path. Human setup and management are
-CLI-first; MCP and the JSON API are only protocol surfaces for clients,
-automation, and smoke checks. The default help output is intentionally short;
+`check` is safe to run before exposing real folders. It creates a temporary
+config and workspace, starts a loopback HTTP MCP server, verifies `/healthz`,
+the local JSON API, MCP initialize, tools/list, `get_computer_info`, and one
+read-only `computer_operation`, then removes the temporary files.
+
+`quickstart --json` exposes `commands.check` for the optional isolated install
+check. `commands.selfTest` remains as a compatibility alias for older agents
+that already consumed the previous JSON field.
+
+There is no web dashboard in the product path. Human setup and management are
+CLI-first; MCP and the JSON API are only protocol surfaces for clients,
+automation, and smoke checks. The default help output is intentionally short;
 use `computer-linker help advanced` for service, config, API, and compatibility
 commands. ChatGPT-specific setup exports are compatibility helpers under
 `computer-linker help chatgpt`; prefer the generic MCP client commands first.

package/dist/cli.js

@@ -84,6 +84,9 @@ async function main(argv) {
         case "status":
             status(args);
             return;
+        case "check":
+            await selfTest(args, "check");
+            return;
         case "self-test":
             await selfTest(args);
             return;
@@ -143,7 +146,7 @@ function normalizeCommand(command) {
         throw new Error("connect-profile was removed; use `computer-linker client chatgpt profile` only when ChatGPT asks for connector-specific fields.");
     if (command === "chatgpt")
         throw new Error("chatgpt was removed; use `computer-linker client chatgpt <subcommand>` only when ChatGPT asks for connector-specific fields.");
-    if (command === "init" || command === "start" || command === "quickstart" || command === "status" || command === "self-test" || command === "expose" || command === "tunnel" || command === "service" || command === "workspace" || command === "process" || command === "screen" || command === "doctor" || command === "diagnose" || command === "history" || command === "profile" || command === "client" || command === "config" || command === "setup")
+    if (command === "init" || command === "start" || command === "quickstart" || command === "status" || command === "check" || command === "self-test" || command === "expose" || command === "tunnel" || command === "service" || command === "workspace" || command === "process" || command === "screen" || command === "doctor" || command === "diagnose" || command === "history" || command === "profile" || command === "client" || command === "config" || command === "setup")
         return command;
     if (command === "version" || command === "--version" || command === "-v")
         return "version";
@@ -166,9 +169,12 @@ function status(args) {
     }
     process.stdout.write(args.includes("--details") ? formatDetailedCliStatus(report) : formatCliStatus(report));
 }
-async function selfTest(args) {
+async function selfTest(args, commandLabel = "self-test") {
     if (hasHelpFlag(args)) {
-        printSelfTestHelp();
+        if (commandLabel === "check")
+            printCheckHelp();
+        else
+            printSelfTestHelp();
         return;
     }
     const unknown = args.filter((arg, index) => (arg !== "--json" &&
@@ -176,8 +182,8 @@ async function selfTest(args) {
         arg !== "--timeout-ms" &&
         args[index - 1] !== "--timeout-ms"));
     if (unknown.length > 0)
-        throw new Error(`Unknown self-test option: ${unknown[0]}`);
-    const timeoutMs = readOptionalIntegerOption(args, "--timeout-ms", "self-test --timeout-ms") ?? 15000;
+        throw new Error(`Unknown ${commandLabel} option: ${unknown[0]}`);
+    const timeoutMs = readOptionalIntegerOption(args, "--timeout-ms", `${commandLabel} --timeout-ms`) ?? 15000;
     const keepTemp = args.includes("--keep-temp");
     const tempRoot = mkdtempSync(join(tmpdir(), "computer-linker-self-test-"));
     const configDir = join(tempRoot, "config");
@@ -3484,11 +3490,12 @@ function buildQuickstartReport(options) {
         "Use the startup check printed by start as the first readiness signal.",
         "Run client setup --show-token only on a trusted local screen when configuring client auth.",
         "Use client setup --details when the MCP client or agent needs full setup instructions.",
-        "Use self-test only when you want an isolated install check.",
+        "Use check only when you want an isolated install check.",
     ];
     if (options.tunnelProvider) {
         nextActions.push("Use tunnel status and connection history to confirm traffic reaches /mcp only.");
     }
+    const checkCommand = formatCliCommand([...commandParts, "check"]);
     return {
         kind: "computer-linker-quickstart",
         schemaVersion: 1,
@@ -3507,7 +3514,8 @@ function buildQuickstartReport(options) {
             openaiTunnelId: options.tunnelProvider === "openai" ? options.openaiTunnelId ?? "tunnel_..." : null,
         },
         commands: {
-            selfTest: formatCliCommand([...commandParts, "self-test"]),
+            check: checkCommand,
+            selfTest: checkCommand,
             start: formatCliCommand(startParts),
             status: formatCliCommand([...commandParts, "status"]),
             token: formatCliCommand([...commandParts, "client", "setup", "--show-token"]),
@@ -3568,7 +3576,7 @@ function printQuickstartReport(report) {
         console.log(`   ${report.commands.tunnelStatus}`);
     if (report.commands.historyConnections)
         console.log(`   ${report.commands.historyConnections}`);
-    console.log(`   optional isolated install check: ${report.commands.selfTest}`);
+    console.log(`   optional isolated install check: ${report.commands.check}`);
 }
 function quickstartCommandParts() {
     return invocationCommandParts();
@@ -3667,6 +3675,10 @@ function printHelp(args = []) {
         printStatusHelp();
         return;
     }
+    if (topic === "check" && rest.length === 0) {
+        printCheckHelp();
+        return;
+    }
     if ((topic === "self-test" || topic === "selftest") && rest.length === 0) {
         printSelfTestHelp();
         return;
@@ -3753,14 +3765,16 @@ function printCoreHelp() {
         "Usage:",
         "  computer-linker start <workspace-path>",
         "  computer-linker start <workspace-path> --tunnel openai|tailscale|cloudflare",
+        "  computer-linker check",
         "  computer-linker client setup",
         "  computer-linker status",
         "  computer-linker help advanced",
         "",
         "First run:",
-        "  1. Start local: computer-linker start C:\\Projects\\my-app",
-        "  2. Connect client: computer-linker client setup",
-        "  3. Check state: computer-linker status",
+        "  1. Optional install check: computer-linker check",
+        "  2. Start local: computer-linker start C:\\Projects\\my-app",
+        "  3. Connect client: computer-linker client setup",
+        "  4. Check state: computer-linker status",
         "",
         "Cloud client:",
         "  computer-linker start C:\\Projects\\my-app --tunnel openai --tunnel-id tunnel_...",
@@ -3777,7 +3791,7 @@ function printCoreHelp() {
         "  By default, start allows file edits and approved project commands for normal development work.",
         "  Use --read-only to inspect only; use --full-trust only when Codex and screen capture are intended.",
         "  Tokens stay hidden by default; use client setup --show-token only on a trusted local setup screen.",
-        "  Details: computer-linker help start | computer-linker help client setup | computer-linker help advanced",
+        "  Details: computer-linker help check | computer-linker help start | computer-linker help client setup | computer-linker help advanced",
     ]);
 }
 function printStartHelp() {
@@ -4063,6 +4077,22 @@ function printSelfTestHelp() {
         "  computer-linker self-test",
     ].join("\n"));
 }
+function printCheckHelp() {
+    console.log([
+        "Computer Linker check",
+        "",
+        "Usage:",
+        "  computer-linker check [--json] [--keep-temp] [--timeout-ms ms]",
+        "",
+        "What it does:",
+        "  Runs an isolated install check without touching your real config or folders.",
+        "  Creates a temporary config and workspace, starts a loopback MCP server,",
+        "  verifies health, MCP initialize, tools/list, get_computer_info, and one read-only computer_operation.",
+        "",
+        "Example:",
+        "  computer-linker check",
+    ].join("\n"));
+}
 function printDoctorHelp() {
     console.log([
         "Computer Linker doctor",
@@ -4462,6 +4492,7 @@ function printAdvancedHelp() {
         "  computer-linker start --tunnel tailscale",
         "  computer-linker start --tunnel openai --tunnel-id tunnel_...",
         "  computer-linker status [--details] [--json]",
+        "  computer-linker check [--json] [--keep-temp] [--timeout-ms ms]",
         "  computer-linker self-test [--json] [--keep-temp] [--timeout-ms ms]",
         "  computer-linker process list <workspace-id> [--json]",
         "  computer-linker process read <workspace-id> <process-id> [--json]",

package/docs/architecture.md

@@ -20,10 +20,10 @@ manually before a wider release. The local and CI release gate is
 the progress-reporting test runner, build, and package smoke.
 The package smoke uses `npm pack --dry-run` to verify packed files, CLI bins,
 SDK exports, release docs, security policy, and the published
-`computer_operation` schema, then creates a real `.tgz`, installs it into a
-temporary consumer project, runs the installed `computer-linker` bin, verifies
-installed `self-test`, `setup`, and `status` against isolated config
-directories, and imports the installed SDK entrypoint. The package build uses
+`computer_operation` schema, then creates a real `.tgz`, installs it into a
+temporary consumer project, runs the installed `computer-linker` bin, verifies
+installed `check`, `setup`, and `status` against isolated config
+directories, and imports the installed SDK entrypoint. The package build uses
 `tsconfig.build.json` so tests are typechecked but are not emitted into the
 runtime package.
 
@@ -414,9 +414,10 @@ surface for the same config file used by the MCP server:
   mode, local MCP URL, auth summary, workspace/tunnel summary, user-facing
   readiness, and the next few actions. `status --details` prints the full
   workspace rows, warnings, running tunnel rows, and all next actions.
-- `computer-linker self-test` creates an isolated temporary config/workspace,
-  starts the loopback HTTP MCP server, runs the generic MCP SDK smoke flow, and
-  exits non-zero when the installed CLI/server/tool flow is not working.
+- `computer-linker check` creates an isolated temporary config/workspace,
+  starts the loopback HTTP MCP server, runs the generic MCP SDK smoke flow, and
+  exits non-zero when the installed CLI/server/tool flow is not working.
+  `computer-linker self-test` remains available as a compatibility command.
 - `computer-linker doctor` shows full runtime diagnostics, startup readiness,
   local MCP/API URLs, security findings, tool availability, release readiness,
   and next actions.

package/docs/manual-test-plan.md

@@ -11,26 +11,26 @@ installed package instead, replace `npm run dev --` with `computer-linker`.
 
 ```bash
 npm ci
-npm run product:check
-npm run alpha:check
-npm run public:mirror -- --dry-run --remote <github-owner>/<public-repo>
-npm run dev -- self-test
+npm run product:check
+npm run alpha:check
+npm run public:mirror -- --dry-run --remote <github-owner>/<public-repo>
+npm run dev -- check
 ```
 
 Expected:
 
-- typecheck, tests, build, release validation, and package smoke pass
-- package smoke reports `computer-linker-<version>.tgz` and verifies a
-  temporary consumer install, installed CLI execution, installed self-test,
-  isolated setup/status, and SDK import
+- typecheck, tests, build, release validation, and package smoke pass
+- package smoke reports `computer-linker-<version>.tgz` and verifies a
+  temporary consumer install, installed CLI execution, installed check,
+  isolated setup/status, and SDK import
 - alpha readiness reports `status: ready`, or `status: needs_attention` only
   because preserved Git history must be published through `public:mirror`
 - `public:mirror -- --dry-run --remote ...` reports the mirror dry-run is
   publishable when the fresh public mirror path is accepted and the other gates
   pass; before a real mirror release, resolve any `release tag check: blocked
   for real run` changelog warning
-- `self-test` reports `ready: yes` and verifies the local MCP SDK tool flow
-  without touching real user workspaces
+- `check` reports `ready: yes` and verifies the local MCP SDK tool flow
+  without touching real user workspaces
 - external MCP client/tunnel evidence is still pending until the later tunnel
   smoke step writes `.computer-linker-alpha-evidence.json`
 
@@ -129,10 +129,10 @@ npm run dev -- start . --id app
 Terminal B:
 
 ```bash
-npm run dev -- doctor
-npm run dev -- status
-npm run dev -- self-test
-npm run dev -- profile
+npm run dev -- doctor
+npm run dev -- status
+npm run dev -- check
+npm run dev -- profile
 npm run dev -- client setup
 npm run dev -- client setup --details
 npm run dev -- client setup --show-token

package/docs/product-spec.md

@@ -779,7 +779,7 @@ Auth rules:
 
 Smoke tests:
 
-- installed CLI self-test using a temporary config and workspace.
+- installed CLI check using a temporary config and workspace.
 - local MCP initialize, tools/list, `get_computer_info`, and read-only
   `computer_operation` through the MCP SDK.
 - HTTP `/healthz`.

package/docs/release-checklist.md

@@ -17,10 +17,10 @@ This performs:
 - Release metadata validation.
 - TypeScript typecheck.
 - Full test suite.
-- Runtime build.
-- Package smoke check with `npm pack --dry-run`, real `.tgz` creation,
-  temporary consumer install, installed CLI execution, isolated installed
-  `self-test`, `setup` / `status` config smoke, and installed SDK import.
+- Runtime build.
+- Package smoke check with `npm pack --dry-run`, real `.tgz` creation,
+  temporary consumer install, installed CLI execution, isolated installed
+  `check`, `setup` / `status` config smoke, and installed SDK import.
 
 Before publishing a public npm/package artifact, run:
 
@@ -237,10 +237,11 @@ For each shell or Codex-enabled scope, verify:
 
 ## Smoke Commands
 
-```bash
-computer-linker init
-computer-linker self-test
-computer-linker status
+```bash
+computer-linker init
+computer-linker check
+computer-linker self-test
+computer-linker status
 computer-linker status --details
 computer-linker status --json
 computer-linker doctor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easonwumac/computer-linker",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "One computer, one permissioned MCP linker for local workspaces.",
   "type": "module",
   "main": "dist/client.js",