@openscaffold/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# openscaffold
 
-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.
+Connects Claude Code to your OpenScaffold workspace. After one login, every Claude Code session you
+start, in any repo, loads the right customer deployment's briefing, and the OpenScaffold tools
+(search the customer's calls, tickets and emails; read the cited plan; propose plan changes).
+
+```sh
+npx @openscaffold/cli login    # opens your browser: click Approve. That's it.
+npx @openscaffold/cli status   # what's set up and the next step (--json for coding agents)
+npx @openscaffold/cli logout   # removes everything it installed and revokes the login
+```
+
+`login` writes only to your user config (never into a repo):
+
+- `~/.config/openscaffold/credentials.json` (your login, mode 0600)
+- the `openscaffold` MCP server in Claude Code (user scope)
+- a SessionStart hook in `~/.claude/settings.json` that prints the briefing
+- `/os-requirements`, `/os-what-changed`, `/os-check-plan`, `/os-demo-check` in `~/.claude/skills/`
+
+Requires Node 22+ and Claude Code. Set `OPENSCAFFOLD_URL` to point at a self-hosted OpenScaffold.

package/dist/index.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// `npx @openscaffold/cli login | status | session-start | logout` (SPEC §8.4). Node 22+, standard library only.
+import { execFileSync, spawn } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { gitInfo, hasSessionHook, hookCommand, MCP_NAME, skillFile, statusReport, withoutSessionHook, withSessionHook } from "./install.js";
+const CONFIG = join(homedir(), ".config", "openscaffold");
+const CREDENTIALS = join(CONFIG, "credentials.json");
+const CACHE = join(CONFIG, "cache");
+const CLAUDE = join(homedir(), ".claude");
+const SETTINGS = join(CLAUDE, "settings.json");
+const SKILLS = join(CLAUDE, "skills");
+// OPENSCAFFOLD_URL overrides (local dev: http://localhost:3000).
+const DEFAULT_URL = "https://app.openscaffold.ai";
+const readJson = (path, fallback) => {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return fallback;
+    }
+};
+const writeJson = (path, value, mode) => {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value, null, 2) + "\n", mode ? { mode } : undefined);
+    if (mode)
+        chmodSync(path, mode);
+};
+const credentials = () => readJson(CREDENTIALS, null);
+async function api(url, path, body, { token, timeoutMs = 15_000 } = {}) {
+    const res = await fetch(new URL(path, url), {
+        method: "POST",
+        headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    return { status: res.status, body: (await res.json().catch(() => ({}))) };
+}
+function openBrowser(url) {
+    if (process.env.OPENSCAFFOLD_NO_BROWSER)
+        return; // tests and headless machines: the URL is printed
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch { }
+}
+/** Runs `claude …`; returns false if Claude Code isn't on PATH or the command failed. */
+function claude(args) {
+    try {
+        execFileSync("claude", args, { stdio: "ignore", timeout: 30_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// --- login --------------------------------------------------------------------------------------
+async function login() {
+    const url = (process.env.OPENSCAFFOLD_URL ?? credentials()?.api_url ?? DEFAULT_URL).replace(/\/$/, "");
+    const start = await api(url, "/api/connect/start", { client_label: hostname() });
+    if (start.status !== 200)
+        throw new Error(`Couldn't reach OpenScaffold at ${url} (${start.status}).`);
+    const { code, login_url, poll } = start.body;
+    console.log(`Opening ${login_url}\nClick Approve in your browser. The page should show the code ${code}.`);
+    openBrowser(login_url);
+    let creds = null;
+    for (const deadline = Date.now() + 10 * 60_000; Date.now() < deadline;) {
+        await new Promise((r) => setTimeout(r, 2000));
+        const r = await api(url, "/api/connect/exchange", { poll }).catch(() => null);
+        if (r?.status === 200) {
+            creds = { api_url: String(r.body.api_url ?? url), token: String(r.body.token), workspace: r.body.workspace };
+            break;
+        }
+        if (r && r.status !== 202)
+            throw new Error(String(r.body.error ?? "Login failed. Run `npx @openscaffold/cli login` again."));
+    }
+    if (!creds)
+        throw new Error("Timed out waiting for approval. Run `npx @openscaffold/cli login` again.");
+    writeJson(CREDENTIALS, creds, 0o600);
+    const written = [`${CREDENTIALS} (your login, readable only by you)`];
+    // 1. MCP server at user scope (replace any earlier login's).
+    const mcpUrl = `${creds.api_url}/api/mcp/mcp`;
+    const addArgs = ["mcp", "add", "--transport", "http", "--scope", "user", MCP_NAME, mcpUrl, "--header", `Authorization: Bearer ${creds.token}`];
+    claude(["mcp", "remove", "--scope", "user", MCP_NAME]);
+    if (claude(addArgs))
+        written.push(`Claude Code MCP server "${MCP_NAME}" (user scope)`);
+    else
+        console.log(`\nClaude Code wasn't found on PATH. Once it is, run:\n  claude ${addArgs.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(" ")}\n`);
+    // 2. SessionStart hook: loads the right deployment's briefing in every session.
+    writeJson(SETTINGS, withSessionHook(readJson(SETTINGS, {}), hookCommand(process.argv[1], process.execPath)));
+    written.push(`${SETTINGS} (SessionStart hook)`);
+    // 3. Commands as personal skills: /os-requirements, /os-what-changed, /os-check-plan, /os-demo-check.
+    const commands = await fetch(`${creds.api_url}/api/commands`).then((r) => r.json()).catch(() => []);
+    for (const c of commands) {
+        const dir = join(SKILLS, `os-${c.name}`);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "SKILL.md"), skillFile(c));
+    }
+    if (commands.length)
+        written.push(`${SKILLS}/os-* (${commands.map((c) => `/os-${c.name}`).join(", ")})`);
+    const self = hookCommand(process.argv[1], process.execPath).replace(/ session-start$/, "");
+    console.log(`\nLogged in to ${creds.workspace.name}.\nWrote:\n${written.map((w) => `  - ${w}`).join("\n")}\nNothing was written into any repo.\n\nStart Claude Code in any repo; it loads the right customer automatically.\nTo undo everything: ${self} logout`);
+}
+// --- session-start (the SessionStart hook) ------------------------------------------------------
+const readStdin = async () => {
+    if (process.stdin.isTTY)
+        return "";
+    let s = "";
+    for await (const chunk of process.stdin)
+        s += chunk;
+    return s;
+};
+const git = (cwd, args) => {
+    try {
+        return execFileSync("git", ["-C", cwd, ...args], { encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch {
+        return null;
+    }
+};
+/** Prints the briefing. Never breaks a session: on any problem, a cached briefing or one line, exit 0. */
+async function sessionStart() {
+    let hook = {};
+    try {
+        hook = JSON.parse((await readStdin()) || "{}");
+    }
+    catch { }
+    const cwd = hook.cwd ?? process.cwd();
+    const creds = credentials();
+    if (!creds)
+        return console.log("OpenScaffold: not logged in (run `npx @openscaffold/cli login`).");
+    const index = readJson(join(CACHE, "index.json"), {});
+    try {
+        const r = await api(creds.api_url, "/api/sessions/start", { claude_session_id: hook.session_id ?? `manual-${Date.now()}`, cwd, ...gitInfo(git(cwd, ["remote", "get-url", "origin"]), git(cwd, ["branch", "--show-current"])) }, { token: creds.token, timeoutMs: 3000 });
+        if (r.status === 401)
+            return console.log("OpenScaffold: login expired or revoked (run `npx @openscaffold/cli login`).");
+        if (r.status !== 200)
+            throw new Error(String(r.status));
+        const briefing = String(r.body.briefing);
+        console.log(briefing);
+        const dep = r.body.deployment?.id;
+        if (dep) {
+            mkdirSync(CACHE, { recursive: true });
+            writeFileSync(join(CACHE, `${dep}.md`), briefing);
+            writeJson(join(CACHE, "index.json"), { ...index, [cwd]: { deployment: dep, at: new Date().toISOString() } });
+        }
+    }
+    catch {
+        const last = index[cwd];
+        const cached = last && existsSync(join(CACHE, `${last.deployment}.md`)) ? readFileSync(join(CACHE, `${last.deployment}.md`), "utf8") : null;
+        console.log(cached ? `${cached}\n\n(offline, from ${last.at})` : "OpenScaffold: offline");
+    }
+}
+// --- status -------------------------------------------------------------------------------------
+/** Read-only: what's set up on this machine and the next step. `--json` for agents. Always exits 0. */
+async function status() {
+    const creds = credentials();
+    let mcp = null;
+    try {
+        execFileSync("claude", ["mcp", "get", MCP_NAME], { stdio: "ignore", timeout: 15_000 });
+        mcp = true;
+    }
+    catch (e) {
+        mcp = e.code === "ENOENT" ? null : false;
+    }
+    // An authenticated request, so a revoked token isn't reported as ready: the MCP endpoint answers 401 to a bad token.
+    const server = creds
+        ? await fetch(new URL("/api/mcp/mcp", creds.api_url), {
+            method: "POST",
+            headers: { authorization: `Bearer ${creds.token}`, "content-type": "application/json", accept: "application/json, text/event-stream" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" }),
+            signal: AbortSignal.timeout(4000),
+        }).then((r) => (r.status === 401 ? "revoked" : r.status >= 500 ? "down" : "ok"), () => "down")
+        : undefined;
+    // The commands login installs: the server's list when it answers, else whatever os-* skills are on disk.
+    const expected = creds && server === "ok"
+        ? await fetch(new URL("/api/commands", creds.api_url), { signal: AbortSignal.timeout(4000) }).then((r) => r.json()).then((cs) => cs.map((c) => `os-${c.name}`), () => null)
+        : null;
+    const onDisk = existsSync(SKILLS) ? readdirSync(SKILLS).filter((d) => d.startsWith("os-") && existsSync(join(SKILLS, d, "SKILL.md"))) : [];
+    const names = expected ?? onDisk;
+    const state = {
+        workspace: creds?.workspace.name ?? null,
+        apiUrl: creds?.api_url ?? null,
+        server,
+        mcp,
+        hook: hasSessionHook(readJson(SETTINGS, {})),
+        skills: names.filter((n) => onDisk.includes(n)).length,
+        skillsExpected: names.length,
+    };
+    const report = statusReport(state);
+    console.log(process.argv.includes("--json") ? JSON.stringify({ ...state, ready: report.ready, next: report.next }, null, 2) : report.text);
+}
+// --- logout -------------------------------------------------------------------------------------
+async function logout() {
+    const creds = credentials();
+    if (creds)
+        await api(creds.api_url, "/api/connect/revoke", {}, { token: creds.token, timeoutMs: 5000 }).catch(() => null);
+    claude(["mcp", "remove", "--scope", "user", MCP_NAME]);
+    if (existsSync(SETTINGS))
+        writeJson(SETTINGS, withoutSessionHook(readJson(SETTINGS, {})));
+    if (existsSync(SKILLS))
+        for (const d of readdirSync(SKILLS))
+            if (d.startsWith("os-"))
+                rmSync(join(SKILLS, d), { recursive: true, force: true });
+    rmSync(CONFIG, { recursive: true, force: true });
+    console.log("Logged out: token revoked, MCP server, hook, /os-* commands and local credentials removed.");
+}
+// --- main ---------------------------------------------------------------------------------------
+const [cmd] = process.argv.slice(2);
+const commands = { login, status, "session-start": sessionStart, logout };
+const run = commands[cmd ?? ""];
+if (!run) {
+    console.error("Usage: npx @openscaffold/cli <login | status | logout>\n(session-start is run by Claude Code's SessionStart hook)");
+    process.exit(1);
+}
+run().then(() => process.exit(0), (e) => {
+    if (cmd === "session-start") {
+        console.log("OpenScaffold: offline"); // never break a session
+        process.exit(0);
+    }
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});

package/dist/install.js

@@ -0,0 +1,85 @@
+// Pure helpers for what `openscaffold login`/`logout` write into Claude Code (SPEC §8.4).
+// Formats checked against code.claude.com docs (hooks, mcp, skills), 2026-10-23.
+export const MCP_NAME = "openscaffold";
+/** Our hook command mentions openscaffold and ends in `session-start` (npx form or a local build path). */
+const isOurCommand = (cmd) => /openscaffold/.test(cmd) && /\bsession-start"?$/.test(cmd.trim());
+const HOOK_MATCHER = "startup|resume|clear|compact";
+const isOurs = (h) => typeof h.command === "string" && isOurCommand(h.command);
+/** Adds (or replaces) our SessionStart hook; leaves everything else in settings.json as it was. */
+export function withSessionHook(settings, command) {
+    const out = structuredClone(settings);
+    const groups = (out.hooks?.SessionStart ?? [])
+        .map((g) => ({ ...g, hooks: g.hooks.filter((h) => !isOurs(h)) }))
+        .filter((g) => g.hooks.length > 0);
+    groups.push({ matcher: HOOK_MATCHER, hooks: [{ type: "command", command, timeout: 10 }] });
+    out.hooks = { ...out.hooks, SessionStart: groups };
+    return out;
+}
+/** Removes our SessionStart hook (and empty leftovers); leaves other hooks alone. */
+export function withoutSessionHook(settings) {
+    const out = structuredClone(settings);
+    if (!out.hooks?.SessionStart)
+        return out;
+    const groups = out.hooks.SessionStart.map((g) => ({ ...g, hooks: g.hooks.filter((h) => !isOurs(h)) })).filter((g) => g.hooks.length > 0);
+    if (groups.length)
+        out.hooks.SessionStart = groups;
+    else
+        delete out.hooks.SessionStart;
+    if (!Object.keys(out.hooks).length)
+        delete out.hooks;
+    return out;
+}
+/**
+ * The hook command. Published installs run through npx; a local checkout (development) runs its
+ * own built file, so the hook works before the package is on npm.
+ */
+export function hookCommand(selfPath, execPath) {
+    if (/[\\/]_npx[\\/]|[\\/]node_modules[\\/]@openscaffold[\\/]cli[\\/]/.test(selfPath))
+        return `npx -y @openscaffold/cli session-start`;
+    return `${JSON.stringify(execPath)} ${JSON.stringify(selfPath)} session-start`;
+}
+/** A personal skill file for one default command: /os-<name>. */
+export function skillFile(c) {
+    return [
+        "---",
+        `name: os-${c.name}`,
+        `description: ${c.description.replace(/\n/g, " ")} (OpenScaffold)`,
+        "---",
+        "",
+        c.prompt,
+        "",
+        "Use the deployment id from the OpenScaffold briefing in context. If there is none, call the openscaffold `list_deployments` tool and ask the FDE which deployment this is for.",
+        "",
+    ].join("\n");
+}
+/** git remote/branch from `git` output; missing pieces are fine (not a repo, detached HEAD). */
+export function gitInfo(remoteOut, branchOut) {
+    const remote = remoteOut?.trim() || undefined;
+    const branch = branchOut?.trim() || undefined;
+    return { git_remote: remote, git_branch: branch };
+}
+/** Whether our SessionStart hook is in settings.json. */
+export const hasSessionHook = (settings) => (settings.hooks?.SessionStart ?? []).some((g) => g.hooks.some(isOurs));
+const HOSTED = "https://app.openscaffold.ai";
+const RELOGIN = (apiUrl) => `npx @openscaffold/cli login${apiUrl && apiUrl !== HOSTED ? ` (or OPENSCAFFOLD_URL=${HOSTED} npx @openscaffold/cli login to use the hosted app)` : ""}`;
+/**
+ * `openscaffold status`: one line per piece of the setup plus the single next step, in words a person or a
+ * coding agent can act on (the agent onboarding playbook reads it). `mcp: null` = Claude Code isn't on PATH.
+ */
+export function statusReport(s) {
+    const commandsOk = s.skillsExpected > 0 && s.skills >= s.skillsExpected;
+    const lines = [
+        `Signed in:    ${s.workspace ? `yes, workspace "${s.workspace}" (${s.apiUrl}${s.server === "down" ? ", not answering" : s.server === "revoked" ? ", login revoked" : ""})` : "no"}`,
+        `MCP server:   ${s.mcp === null ? "unknown (Claude Code not on PATH)" : s.mcp ? "added" : "missing"}`,
+        `Session hook: ${s.hook ? "installed" : "missing"}`,
+        `Commands:     ${commandsOk ? `${s.skills} /os-* commands` : s.skills ? `${s.skills} of ${s.skillsExpected || "?"} /os-* commands` : "missing"}`,
+    ];
+    const next = !s.workspace || s.server === "revoked" || s.mcp === false || !s.hook || !commandsOk
+        ? `Run: ${RELOGIN(s.apiUrl)} (one browser click to approve).`
+        : s.server !== "ok"
+            ? `${s.apiUrl} isn't answering. If it's a local dev server, start it; otherwise run: ${RELOGIN(s.apiUrl)}.`
+            : s.mcp === null
+                ? "Claude Code isn't on PATH, so the MCP server can't be checked or added. Put `claude` on PATH, then run: npx @openscaffold/cli login."
+                : "Ready. Start a new Claude Code session (or restart this one) to load OpenScaffold.";
+    return { ready: next.startsWith("Ready"), next, text: `OpenScaffold setup\n${lines.map((l) => `  ${l}`).join("\n")}\n\nNext: ${next}` };
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@openscaffold/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Connect Claude Code to your OpenScaffold workspace: each session loads the right customer deployment.",
+  "type": "module",
+  "bin": {
+    "openscaffold": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "tsc"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "typescript": "5.9.3"
+  },
+  "packageManager": "pnpm@9.14.2",
+  "keywords": [
+    "openscaffold",
+    "claude-code",
+    "mcp",
+    "forward-deployed-engineering"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sigma-M-A/openscaffold.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/Sigma-M-A/openscaffold",
+  "publishConfig": {
+    "access": "public"
+  }
+}