@specset/cli 0.2.0 → 0.3.0

package/README.md

@@ -48,16 +48,23 @@ specset agent chat --project <projectId> -m "What mechanical equipment is schedu
 
 Run `specset --help` or `specset <command> --help` for the full command reference.
 
-## Use with Claude and other agents
+## Use with Claude, Codex, and ChatGPT
 
 The package bundles a family of [Agent Skills](https://agentskills.io) that teach AI agents how to drive this CLI safely — a core `specset` skill (setup, auth, GraphQL) plus domain skills for search, project setup, submittals, RFIs, closeout data, agent chat, and org administration:
 
 ```bash
-# Claude Code: install the whole family into ~/.claude/skills
-specset skill install
+# Claude Code: install the whole family into ~/.claude/skills (the default)
+specset skill install --target claude
+
+# Codex or ChatGPT desktop: install into ~/.agents/skills
+specset skill install --target codex
+# `--target chatgpt` is an alias for the same directory
 
 # Install a subset
-specset skill install --only specset --only specset-search
+specset skill install --target codex --only specset --only specset-search
+
+# Override the destination for another agent or a custom setup
+specset skill install --dir /path/to/skills
 
 # See what's bundled
 specset skill list
@@ -67,7 +74,7 @@ specset skill print
 specset skill print specset-submittals
 ```
 
-Re-run `specset skill install` after upgrading the CLI to refresh the installed copies.
+Re-run `specset skill install --target <agent>` after upgrading the CLI to refresh the installed copies.
 
 ## Configuration
 

package/dist/main.js

@@ -28757,6 +28757,52 @@ var drawingComparisonRouting = {
   ]
 };
 
+// apps/cli/src/probes/scenarios/routing/projectScan.ts
+var projectScanRouting = {
+  name: "routing/project-scan",
+  tier: "routing",
+  description: "Flash conversation routes an exhaustive-inventory ask through the project-scan skill and pauses at the startProjectScan approval.",
+  preconditionNotes: "target project needs a processed drawing set",
+  turns: [
+    {
+      kind: "message",
+      text: "I need a complete inventory of every fire damper and combination fire/smoke damper shown on the mechanical drawings \u2014 device type, rating, location, and the sheet and note where each is called out. Use sensible defaults for scoping \u2014 do not ask me questions before starting."
+    }
+  ],
+  assertions: [
+    expectToolCall("loadSkill", { input: { name: "project-scan" } }),
+    expectToolCall("startProjectScan", {
+      state: "approval-requested",
+      minTimes: 1,
+      maxTimes: 1
+    }),
+    custom("scan is scoped to drawing sheets, not the whole project", (ctx) => {
+      const dispatches = ctx.toolCalls().filter((c) => c.toolName === "startProjectScan");
+      const input = dispatches[0]?.input;
+      const scoped = input?.coverageMode === "drawingSheets" && Boolean(
+        input.sheetNumbers?.length || input.disciplines?.length || input.area || input.masterOnly
+      );
+      return {
+        pass: scoped,
+        evidence: `startProjectScan inputs: ${JSON.stringify(dispatches.map((c) => c.input))}`
+      };
+    }),
+    custom("does not attempt the enumeration inline", (ctx) => {
+      const inlineReads = ctx.toolCalls().filter(
+        (c) => ["searchDrawingSheets", "getDrawingSheetContent"].includes(
+          c.toolName
+        )
+      );
+      return {
+        pass: inlineReads.length <= 6,
+        evidence: `${inlineReads.length} inline drawing reads`
+      };
+    }),
+    expectAwaitingApproval("startProjectScan"),
+    expectNoError()
+  ]
+};
+
 // apps/cli/src/probes/scenarios/routing/submittalReview.ts
 var submittalReviewRouting = {
   name: "routing/submittal-review",
@@ -28903,6 +28949,7 @@ var allScenarios = [
   submittalReviewRouting,
   drawingComparisonRouting,
   contractReviewRouting,
+  projectScanRouting,
   userTableSkillRouting,
   userDocumentSkillRouting,
   contractReviewFullLifecycle,
@@ -30125,6 +30172,12 @@ ${authorizeUrl}
   try {
     await open(authorizeUrl.toString());
   } catch {
+    process.stderr.write(
+      `Could not open a browser automatically. Open the URL above manually.
+If your browser is on a different machine (SSH, container), press Ctrl-C
+and run \`specset login --device\` instead.
+`
+    );
   }
   let callback;
   try {
@@ -30158,6 +30211,101 @@ ${authorizeUrl}
   return { userId: user.id, email: user.email, host, accessToken };
 }
 
+// apps/cli/src/oauth/deviceFlow.ts
+var startDeviceAuthorizationDocument = graphql(`
+  mutation Cli_startOAuthDeviceAuthorization($clientId: String!) {
+    startOAuthDeviceAuthorization(clientId: $clientId) {
+      deviceCode
+      userCode
+      expiresIn
+      interval
+    }
+  }
+`);
+var exchangeDeviceCodeDocument = graphql(`
+  mutation Cli_exchangeOAuthDeviceCode(
+    $clientId: String!
+    $deviceCode: String!
+  ) {
+    exchangeOAuthDeviceCode(clientId: $clientId, deviceCode: $deviceCode) {
+      accessToken
+      user {
+        id
+        email
+      }
+    }
+  }
+`);
+function sleep3(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function deviceErrorCode(err) {
+  if (!(err instanceof ClientError)) {
+    return null;
+  }
+  const errors = err.response.errors ?? [];
+  for (const e3 of errors) {
+    const code = e3.extensions?.code;
+    if (typeof code === "string") {
+      return code;
+    }
+  }
+  return null;
+}
+async function runDeviceLoginFlow(host) {
+  const client = createGraphQLClient({ host });
+  const start = await client.request(startDeviceAuthorizationDocument, {
+    clientId: OAUTH_CLIENT_ID
+  });
+  const { deviceCode, userCode, expiresIn, interval } = start.startOAuthDeviceAuthorization;
+  const verificationUrl = `${resolveBaseUrl(host)}/device?code=${encodeURIComponent(userCode)}`;
+  process.stderr.write(
+    `To sign in, open this link in a browser on any device:
+
+    ${verificationUrl}
+
+and approve the code ${userCode}.
+
+Waiting for approval (code expires in ${Math.round(expiresIn / 60)} minutes)...
+`
+  );
+  let intervalMs = interval * 1e3;
+  const deadline = Date.now() + expiresIn * 1e3;
+  while (Date.now() < deadline) {
+    await sleep3(intervalMs);
+    try {
+      const result = await client.request(exchangeDeviceCodeDocument, {
+        clientId: OAUTH_CLIENT_ID,
+        deviceCode
+      });
+      const { accessToken, user } = result.exchangeOAuthDeviceCode;
+      const current = await loadConfig();
+      const next = setHostConfig(current, host, { token: accessToken });
+      await saveConfig({ ...next, currentHost: host });
+      return { userId: user.id, email: user.email, host, accessToken };
+    } catch (err) {
+      const code = deviceErrorCode(err);
+      if (code === "authorization_pending") {
+        continue;
+      }
+      if (code === "slow_down") {
+        intervalMs += 5e3;
+        continue;
+      }
+      if (code === "expired_token") {
+        break;
+      }
+      if (code === "access_denied") {
+        throw new Error("Authorization was denied.");
+      }
+      throw err;
+    }
+  }
+  throw new Error(
+    `The code expired before it was approved. Run \`specset login --device\` again to get a new one.`
+  );
+}
+
 // apps/cli/src/commands/login.ts
 async function loginCommand(flags) {
   const host = resolveActiveHost(this.config, flags.host);
@@ -30167,7 +30315,7 @@ async function loginCommand(flags) {
       `Already logged in to ${host}. Run \`${logoutCmd}\` first.`
     );
   }
-  const result = await runLoginFlow(host);
+  const result = flags.device ? await runDeviceLoginFlow(host) : await runLoginFlow(host);
   printResult(
     this.process,
     flags.json ?? false,
@@ -30186,6 +30334,11 @@ var login = buildCommand({
         brief: "Host to authenticate against (e.g. app.specset.dev, app2.specset.dev, http://localhost:3000). Added to ~/.config/specset/config.yml.",
         optional: true
       },
+      device: {
+        kind: "boolean",
+        brief: "Sign in without a local browser: prints a code you approve from any device (SSH, containers, CI)",
+        optional: true
+      },
       json: {
         kind: "boolean",
         brief: "Emit machine-readable JSON instead of human output",
@@ -30430,9 +30583,12 @@ import path5 from "node:path";
 // apps/cli/src/skillAsset.ts
 import { existsSync as existsSync2, readdirSync, readFileSync } from "node:fs";
 var CORE_SKILL_NAME = "specset";
+var SKILL_VERSION_FILENAME = ".specset-version";
 var skillsRoot = new URL("../skills/", import.meta.url);
 function listPackagedSkillNames() {
-  return readdirSync(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter((entry) => existsSync2(new URL(`${entry.name}/SKILL.md`, skillsRoot))).map((entry) => entry.name).sort((a3, b) => {
+  return readdirSync(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter(
+    (entry) => existsSync2(new URL(`${entry.name}/SKILL.md`, skillsRoot))
+  ).map((entry) => entry.name).sort((a3, b) => {
     if (a3 === CORE_SKILL_NAME) {
       return -1;
     }
@@ -30445,11 +30601,6 @@ function listPackagedSkillNames() {
 function readPackagedSkill(name2) {
   return readFileSync(new URL(`${name2}/SKILL.md`, skillsRoot), "utf8");
 }
-function stampSkillVersion(content, version) {
-  return content.replace(/^---\n/, `---
-version: ${version}
-`);
-}
 function extractSkillVersion(content) {
   return /^version: (.+)$/m.exec(content)?.[1]?.trim() ?? null;
 }
@@ -30468,27 +30619,51 @@ function cliVersion() {
 }
 
 // apps/cli/src/commands/skill/install.ts
-async function installOne(skillsDir, name2, version) {
-  const destFile = path5.join(skillsDir, name2, "SKILL.md");
-  const desired = stampSkillVersion(readPackagedSkill(name2), version);
-  let existing = null;
+var SKILL_TARGET_PATHS = {
+  claude: [".claude", "skills"],
+  codex: [".agents", "skills"],
+  chatgpt: [".agents", "skills"]
+};
+function isSkillInstallTarget(value2) {
+  return Object.hasOwn(SKILL_TARGET_PATHS, value2);
+}
+function defaultSkillsDir(target, homeDir = os2.homedir()) {
+  return path5.join(homeDir, ...SKILL_TARGET_PATHS[target]);
+}
+async function readOptionalText(file) {
   try {
-    existing = await fs2.readFile(destFile, "utf8");
+    return await fs2.readFile(file, "utf8");
   } catch (err) {
-    if (err.code !== "ENOENT") {
-      throw err;
+    if (err.code === "ENOENT") {
+      return null;
     }
+    throw err;
   }
-  if (existing === desired) {
+}
+async function installOne(skillsDir, name2, version) {
+  const destDir = path5.join(skillsDir, name2);
+  const destFile = path5.join(destDir, "SKILL.md");
+  const versionFile = path5.join(destDir, SKILL_VERSION_FILENAME);
+  const desired = readPackagedSkill(name2);
+  const [existing, recordedVersion] = await Promise.all([
+    readOptionalText(destFile),
+    readOptionalText(versionFile)
+  ]);
+  const previousVersion = recordedVersion?.trim() || (existing ? extractSkillVersion(existing) : null);
+  if (existing === desired && previousVersion === version) {
     return { name: name2, path: destFile, action: "current", previousVersion: null };
   }
-  await fs2.mkdir(path5.dirname(destFile), { recursive: true });
-  await fs2.writeFile(destFile, desired);
+  await fs2.mkdir(destDir, { recursive: true });
+  await Promise.all([
+    fs2.writeFile(destFile, desired),
+    fs2.writeFile(versionFile, `${version}
+`)
+  ]);
   return {
     name: name2,
     path: destFile,
     action: existing ? "updated" : "installed",
-    previousVersion: existing ? extractSkillVersion(existing) : null
+    previousVersion: existing ? previousVersion : null
   };
 }
 async function findOrphanedSkills(skillsDir, packagedNames) {
@@ -30508,6 +30683,13 @@ async function findOrphanedSkills(skillsDir, packagedNames) {
       continue;
     }
     try {
+      const recordedVersion = await readOptionalText(
+        path5.join(skillsDir, entry.name, SKILL_VERSION_FILENAME)
+      );
+      if (recordedVersion?.trim()) {
+        orphans.push(path5.join(skillsDir, entry.name));
+        continue;
+      }
       const content = await fs2.readFile(
         path5.join(skillsDir, entry.name, "SKILL.md"),
         "utf8"
@@ -30521,7 +30703,14 @@ async function findOrphanedSkills(skillsDir, packagedNames) {
   return orphans;
 }
 async function skillInstallCommand(flags) {
-  const skillsDir = flags.dir?.trim() || path5.join(os2.homedir(), ".claude", "skills");
+  const targetName = flags.target?.trim() || "claude";
+  if (!isSkillInstallTarget(targetName)) {
+    return new Error(
+      `Unknown target "${targetName}". Available: ${Object.keys(SKILL_TARGET_PATHS).join(", ")}`
+    );
+  }
+  const target = targetName;
+  const skillsDir = flags.dir?.trim() || defaultSkillsDir(target);
   const version = cliVersion();
   const packagedNames = listPackagedSkillNames();
   let names = packagedNames;
@@ -30561,7 +30750,7 @@ async function skillInstallCommand(flags) {
   printResult(
     this.process,
     flags.json ?? false,
-    { dir: skillsDir, version, skills: results, orphans },
+    { target, dir: skillsDir, version, skills: results, orphans },
     lines.join("\n")
   );
 }
@@ -30570,10 +30759,16 @@ var skillInstall = buildCommand({
   parameters: {
     positional: { kind: "tuple", parameters: [] },
     flags: {
+      target: {
+        kind: "parsed",
+        parse: String,
+        brief: "Agent target: claude (~/.claude/skills), codex or chatgpt (~/.agents/skills); defaults to claude",
+        optional: true
+      },
       dir: {
         kind: "parsed",
         parse: String,
-        brief: "Skills directory to install into (defaults to ~/.claude/skills)",
+        brief: "Override the target skills directory",
         optional: true
       },
       only: {
@@ -30591,7 +30786,7 @@ var skillInstall = buildCommand({
     }
   },
   docs: {
-    brief: "Install the Specset agent skills into a skills directory (re-run after upgrading to refresh)"
+    brief: "Install the Specset agent skills for Claude, Codex, or ChatGPT (re-run after upgrading to refresh)"
   }
 });
 
@@ -30631,9 +30826,7 @@ async function skillPrintCommand(_flags, name2) {
       `Unknown skill "${skillName}". Available: ${available.join(", ")}`
     );
   }
-  this.process.stdout.write(
-    stampSkillVersion(readPackagedSkill(skillName), cliVersion())
-  );
+  this.process.stdout.write(readPackagedSkill(skillName));
 }
 var skillPrint = buildCommand({
   func: skillPrintCommand,
@@ -30652,7 +30845,7 @@ var skillPrint = buildCommand({
     flags: {}
   },
   docs: {
-    brief: "Print a bundled Specset agent skill to stdout (for non-Claude agents / custom setups)"
+    brief: "Print a bundled Specset agent skill to stdout for custom setups"
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specset/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Command-line interface for Specset — authenticate, run GraphQL queries, and chat with Specset project agents.",
   "license": "Apache-2.0",
   "homepage": "https://specset.com",

package/skills/specset/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: specset
 description: Core CLI for Specset — install, authenticate, switch organizations, and run GraphQL with `specset api`. Start here for any Specset task, and whenever a specset command fails with auth or org errors.
-allowed-tools: Bash, Read, AskUserQuestion
+allowed-tools: Bash Read AskUserQuestion
 ---
 
 # Specset CLI (`specset`)
@@ -24,7 +24,7 @@ This is the core skill — setup and mechanics only. Domain workflows live in si
 | `specset-agent` | Delegating deep project questions to Specset's in-app AI agent |
 | `specset-admin` | Org members, invites, and whitelabel branding |
 
-`specset skill install` installs and updates the whole family (`specset skill list` shows what's bundled) — if a skill named above is missing from your skills directory, run it.
+`specset skill install --target <claude|codex|chatgpt>` installs and updates the whole family (`specset skill list` shows what's bundled) — if a skill named above is missing from your skills directory, run it for the current agent.
 
 ## First-Run Setup
 
@@ -44,7 +44,15 @@ Requires Node.js 20+ with npm. If `npm` itself is missing, stop and ask the user
 specset login
 ```
 
-Login is interactive by design — never try to bypass it or handle credentials directly. On a headless machine (no browser), login isn't possible; direct the user to a machine with a browser. Don't launch a login mid-task without telling the user what's happening.
+Login is interactive by design — never try to bypass it or handle credentials directly. Don't launch a login mid-task without telling the user what's happening.
+
+**On a headless machine** (container, SSH, CI — anywhere the browser isn't on this machine), use the device flow instead:
+
+```bash
+specset login --device
+```
+
+It prints a short code and a link (`https://<host>/device?code=XXXX-XXXX`). Show both to the user and ask them to open the link on any device and approve; the command completes on its own once they do. The code expires after 15 minutes — if it does, run the command again for a fresh one.
 
 3. Pick the active organization (required for org-scoped queries):
 
@@ -167,5 +175,5 @@ Processing large PDF sets takes minutes; poll every 15–30 seconds and tell the
 - `Not logged in` — run `specset login` (opens the user's browser; tell them to complete sign-in there).
 - `No active organization selected` — run `specset org list`, then `specset org use <slug>`.
 - A lookup by id returns `null` without an error — the record usually belongs to a different org than the active one; check `specset auth status` and switch with `specset org use <slug>`.
-- Login requires a browser; on a headless machine, run the CLI from a machine with a browser first, or contact Specset support about headless options.
-- After upgrading the CLI (`npm i -g @specset/cli@latest`), refresh the skills with `specset skill install`.
+- Login hangs or the browser can't reach this machine (SSH, container, CI) — use `specset login --device`: it prints a code + link the user approves from any device.
+- After upgrading the CLI (`npm i -g @specset/cli@latest`), refresh the skills with `specset skill install --target <claude|codex|chatgpt>`.

package/skills/specset-admin/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: specset-admin
 description: Use when administering a Specset organization — inviting and managing members and roles, or applying whitelabel branding (colors, logos) — for org membership, permissions, or appearance tasks.
-allowed-tools: Bash, Read, AskUserQuestion
+allowed-tools: Bash Read AskUserQuestion
 ---
 
 # Org Administration

package/skills/specset-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: specset-agent
 description: Ask Specset's in-project AI agent questions that need deep project understanding — schedules, spec interpretation, cross-document analysis — via `specset agent chat`. Use when raw GraphQL isn't enough or when unsure how to answer from data.
-allowed-tools: Bash, Read, AskUserQuestion
+allowed-tools: Bash Read AskUserQuestion
 ---
 
 # Specset Agent Chat

package/skills/specset-closeout/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: specset-closeout
 description: Use when managing Specset closeout and facilities data — assets, locations, products, companies, warranties, and maintenance tasks, plus their documents and links — for closeout package or O&M/facilities tasks.
-allowed-tools: Bash, Read, AskUserQuestion
+allowed-tools: Bash Read AskUserQuestion
 ---
 
 # Closeout & Facilities Data

package/skills/specset-projects/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: specset-projects
 description: Use when standing up a new Specset project or adding document sets to one — create the project, upload spec/drawing PDFs, monitor processing, and publish spec sets and drawing sets.
-allowed-tools: Bash, Read, AskUserQuestion
+allowed-tools: Bash Read AskUserQuestion
 ---
 
 # Specset Projects

package/skills/specset-rfis/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: specset-rfis
 description: Manage Specset RFIs — list, search, create, update, and record responses including the official answer of record. Use for any RFI logging or tracking task.
-allowed-tools: Bash, Read, AskUserQuestion
+allowed-tools: Bash Read AskUserQuestion
 ---
 
 # Specset RFIs

package/skills/specset-search/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: specset-search
 description: Use when the user asks to find, look up, or locate anything in their Specset projects — semantic and keyword search across specs, drawing sheets, submittals, RFIs, documents, and closeout records.
-allowed-tools: Bash, Read, AskUserQuestion
+allowed-tools: Bash Read AskUserQuestion
 ---
 
 # Specset Search

package/skills/specset-submittals/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: specset-submittals
 description: Manage Specset submittals — list, search, create, revise, attach files, track approvers, and run AI spec-compliance reviews. Use for any submittal log or submittal review task.
-allowed-tools: Bash, Read, AskUserQuestion
+allowed-tools: Bash Read AskUserQuestion
 ---
 
 # Specset Submittals