trustci 0.2.2 → 0.3.1

package/README.md

@@ -10,7 +10,7 @@ Setting up trusted publishing one package at a time is tedious in a monorepo.
 
 ## Requirements
 
-- **npm** 11.5.1 or later (for `npm trust`)
+- **npm** 11.15.0 or later (for `npm trust` with `--allow-publish` / `--allow-stage-publish`)
 - **Node** 22.14.0 or later
 
 ## Usage
@@ -32,7 +32,7 @@ npx trustci list
 | ---------- | ---------------------------------------------------------------------------------------------- | --------------- |
 | `github`   | `--repo <owner/repo>` `--file <workflow>`                                                       | `--env <name>`  |
 | `gitlab`   | `--project <group/project>` (or `--repo`) `--file <workflow>`                                   | `--env <name>`  |
-| `circleci` | `--org-id` `--project-id` `--pipeline-definition-id` `--vcs-origin <host/owner/repo>`                      | `--context-id` (repeatable) |
+| `circleci` | A CircleCI token, or all of `--org-id` `--project-id` `--pipeline-definition-id` | `--vcs-origin <host/owner/repo>` (inferred), `--circle-token`, `--file`, `--context-id` (repeatable) |
 
 At least one of `--allow-publish` / `--allow-stage-publish` is required.
 
@@ -40,7 +40,12 @@ At least one of `--allow-publish` / `--allow-stage-publish` is required.
 # GitLab
 npx trustci --provider gitlab --project me/repo --file .gitlab-ci.yml --allow-publish -y
 
-# CircleCI (vcs-origin is host/owner/repo; a leading https:// is stripped automatically)
+# CircleCI — minimal form: UUIDs are resolved via the API and --vcs-origin
+# is inferred, so a token (here via the environment) is all you need to add
+CIRCLE_TOKEN=... npx trustci --provider circleci --allow-publish
+
+# CircleCI — fully explicit form
+# (vcs-origin is host/owner/repo; a leading https:// is stripped automatically)
 npx trustci --provider circleci \
   --org-id <uuid> --project-id <uuid> --pipeline-definition-id <uuid> \
   --vcs-origin github.com/me/repo \
@@ -48,6 +53,47 @@ npx trustci --provider circleci \
   --allow-publish
 ```
 
+#### CircleCI `--vcs-origin`
+
+When `--vcs-origin` is omitted, trustci takes it from the root `package.json`
+`repository` field (URL, `git+https://…`, `git@host:owner/repo`, or the
+`github:` / `gitlab:` / `bitbucket:` / `owner/repo` shorthands), then from
+`git remote get-url origin`. It prints which one it used, and warns when the two
+disagree (`package.json` wins, since it is committed rather than clone-specific).
+
+#### CircleCI token lookup
+
+When any of the three UUIDs is missing, trustci resolves it through the CircleCI
+API v2. The token is taken from the first of these that is set, and trustci
+prints which one it used (never the token itself):
+
+1. `--circle-token`
+2. `CIRCLE_TOKEN` (circleci CLI v1, chunk)
+3. `CIRCLECI_TOKEN` (chunk)
+4. `CIRCLE_CLI_TOKEN` (circleci CLI v1, legacy alias)
+5. `CIRCLECI_CLI_TOKEN` (circleci CLI v0.1)
+6. `token` in `~/.circleci/cli.yml`, written by `circleci setup` in circleci CLI v0.1.
+   It is ignored when its `host` is not `https://circleci.com`.
+
+The OS keychain, where circleci CLI v1 and chunk store tokens by default, is not read.
+When all three UUIDs are given, no token is looked up.
+
+#### CircleCI pipeline definitions and `--file`
+
+A missing `--pipeline-definition-id` is resolved by listing the project's
+pipeline definitions. When there is exactly one, it is used automatically.
+When the project has several — e.g. a config sourced from another repository
+alongside `.circleci/config.yml` — pass `--file` with either the definition's
+config file path or its name; the error message lists the candidates:
+
+```bash
+npx trustci --provider circleci --allow-publish \
+  --file workflows/publish/npm-polyrepo-bun-semantic-release.yaml
+```
+
+`--file` is only used for this lookup — it is not passed to `npm trust`, and
+it has no effect when `--pipeline-definition-id` is given explicitly.
+
 ### Common options
 
 | Flag                     | Description                                          |
@@ -70,6 +116,18 @@ Patterns are read from the first of:
 Packages marked `"private": true` are always excluded. On a real (non-dry) run,
 packages not yet published to the registry are skipped with a warning.
 
+## Agent skill
+
+The repository ships an [Agent Skill](https://agentskills.io/) at
+[`skills/trustci/SKILL.md`](https://github.com/hideokamoto/trustci/blob/main/skills/trustci/SKILL.md)
+that teaches coding agents (Claude Code, Codex, Cursor, …) to run trustci safely:
+dry-run first, then a real run only after you confirm. Install it with the
+[`skills`](https://github.com/vercel-labs/skills) CLI:
+
+```bash
+npx skills add hideokamoto/trustci
+```
+
 ## Development
 
 Built with [Bun](https://bun.sh), ships zero runtime dependencies, and the
@@ -82,6 +140,15 @@ bun run typecheck
 bun run build   # -> dist/cli.js (npx entry point), via `bun build --target node`
 ```
 
+The documentation site lives in `docs/` ([Astro Starlight](https://starlight.astro.build/)):
+
+```bash
+cd docs
+bun install
+bun run dev     # local preview
+bun run build   # -> docs/dist
+```
+
 `bun install` also enables a husky `commit-msg` hook that runs
 [commitlint](https://commitlint.js.org/) with `@commitlint/config-conventional`,
 so every commit must be a [Conventional Commit](https://www.conventionalcommits.org/).

package/dist/cli.js

@@ -37,13 +37,24 @@ function projectSlugFromVcsOrigin(origin) {
   }
   return `${vcsType}/${parts[0]}/${parts[1]}`;
 }
+
+class CircleApiError extends Error {
+  status;
+  path;
+  body;
+  constructor(status, path, body) {
+    super(`CircleCI API error (${status}) for ${path}: ${body}`);
+    this.status = status;
+    this.path = path;
+    this.body = body;
+  }
+}
 async function circleGet(token, path) {
   const response = await fetch(`${BASE_URL}${path}`, {
     headers: { "Circle-Token": token, Accept: "application/json" }
   });
   if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`CircleCI API error (${response.status}) for ${path}: ${body}`);
+    throw new CircleApiError(response.status, path, await response.text());
   }
   return response.json();
 }
@@ -168,26 +179,17 @@ function parseCliArgs(argv) {
       break;
     }
     case "circleci": {
+      const rawVcsOrigin = values["vcs-origin"];
       let vcsOrigin;
       try {
-        vcsOrigin = normalizeVcsOrigin(require_(values["vcs-origin"], "vcs-origin", "circleci"));
+        vcsOrigin = rawVcsOrigin === undefined ? undefined : normalizeVcsOrigin(rawVcsOrigin);
       } catch (e) {
-        if (e instanceof ArgError)
-          throw e;
         throw new ArgError(`--${e.message}`);
       }
       const circleToken = values["circle-token"];
       const orgId = values["org-id"];
       const projectId = values["project-id"];
       const pipelineDefinitionId = values["pipeline-definition-id"];
-      if (!circleToken) {
-        if (!orgId)
-          throw new ArgError("--org-id is required for --provider circleci (or provide --circle-token for auto-resolution).");
-        if (!projectId)
-          throw new ArgError("--project-id is required for --provider circleci (or provide --circle-token for auto-resolution).");
-        if (!pipelineDefinitionId)
-          throw new ArgError("--pipeline-definition-id is required for --provider circleci (or provide --circle-token for auto-resolution).");
-      }
       providerOptions = {
         provider: "circleci",
         circleToken,
@@ -226,33 +228,217 @@ function runInherit(cmd, args) {
   return res.status ?? (res.error || res.signal ? 1 : 0);
 }
 
+// src/resolve.ts
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+
+// src/token.ts
+import { join } from "node:path";
+var DEFAULT_HOST = "https://circleci.com";
+var LEGACY_CLI_YML = "~/.circleci/cli.yml";
+var TOKEN_ENV_VARS = ["CIRCLE_TOKEN", "CIRCLECI_TOKEN", "CIRCLE_CLI_TOKEN", "CIRCLECI_CLI_TOKEN"];
+var TOKEN_SOURCES = ["--circle-token", ...TOKEN_ENV_VARS, LEGACY_CLI_YML];
+function parseLegacyCliYml(content) {
+  const out = {};
+  for (const raw of content.split(/\r?\n/)) {
+    const m = /^(token|host):(.*)$/.exec(raw);
+    if (!m)
+      continue;
+    const value = parseScalar(m[2].trim());
+    if (value)
+      out[m[1]] = value;
+  }
+  return out;
+}
+function parseScalar(v) {
+  const quoted = /^(["'])(.*)\1(\s+#.*)?$/.exec(v);
+  if (quoted)
+    return quoted[2];
+  return v.replace(/\s+#.*$/, "").trim();
+}
+function resolveCircleToken(input) {
+  if (input.flag)
+    return { token: input.flag, source: "--circle-token", notes: [] };
+  for (const name of TOKEN_ENV_VARS) {
+    const value = input.env[name];
+    if (value)
+      return { token: value, source: name, notes: [] };
+  }
+  const content = input.readFile(join(input.homedir, ".circleci", "cli.yml"));
+  if (content === null)
+    return { token: undefined, notes: [] };
+  const { token, host } = parseLegacyCliYml(content);
+  if (!token)
+    return { token: undefined, notes: [] };
+  if (token === "|" || token === ">" || /^[|>][-+0-9]*$/.test(token)) {
+    return { token: undefined, notes: [`skipped ${LEGACY_CLI_YML}: its token is not a single-line value trustci can read`] };
+  }
+  if (host && host.replace(/\/+$/, "") !== DEFAULT_HOST) {
+    return { token: undefined, notes: [`skipped ${LEGACY_CLI_YML}: its token is for ${host}, not ${DEFAULT_HOST}`] };
+  }
+  return { token, source: LEGACY_CLI_YML, notes: [] };
+}
+
+// src/vcs.ts
+var SHORTHAND_HOSTS = {
+  github: "github.com",
+  gitlab: "gitlab.com",
+  bitbucket: "bitbucket.org"
+};
+var PACKAGE_JSON = "package.json repository";
+var GIT_REMOTE = "git remote origin";
+function parseRepositoryUrl(input) {
+  const s = input.trim();
+  let host;
+  let path;
+  const shorthand = /^(github|gitlab|bitbucket):(.+)$/.exec(s);
+  const scp = /^[^@/\s]+@([^:/\s]+):(.+)$/.exec(s);
+  if (shorthand) {
+    host = SHORTHAND_HOSTS[shorthand[1]];
+    path = shorthand[2];
+  } else if (/^[^/:\s]+\/[^/:\s]+$/.test(s)) {
+    host = "github.com";
+    path = s;
+  } else if (scp) {
+    host = scp[1];
+    path = scp[2];
+  } else {
+    let url;
+    try {
+      url = new URL(s.replace(/^git\+/, ""));
+    } catch {
+      return null;
+    }
+    if (!["https:", "http:", "ssh:", "git:"].includes(url.protocol) || !url.hostname)
+      return null;
+    host = url.hostname;
+    path = url.pathname;
+  }
+  const parts = path.replace(/#.*$/, "").replace(/^\/+|\/+$/g, "").replace(/\.git$/, "").split("/");
+  if (parts.length < 2 || parts.some((p) => !p))
+    return null;
+  return `${host}/${parts.join("/")}`;
+}
+function repositoryFromPackageJson(repository) {
+  if (typeof repository === "string")
+    return repository;
+  if (repository && typeof repository === "object" && "url" in repository) {
+    const url = repository.url;
+    if (typeof url === "string")
+      return url;
+  }
+  return;
+}
+function resolveVcsOrigin(input) {
+  if (input.flag)
+    return { value: input.flag, source: "--vcs-origin", warnings: [] };
+  const warnings = [];
+  const fromGit = input.gitRemote ? parseRepositoryUrl(input.gitRemote) : null;
+  if (input.pkgRepository !== undefined) {
+    const fromPkg = parseRepositoryUrl(input.pkgRepository);
+    if (fromPkg) {
+      if (fromGit && fromGit !== fromPkg) {
+        warnings.push(`${PACKAGE_JSON} (${fromPkg}) differs from ${GIT_REMOTE} (${fromGit}); using ${fromPkg}`);
+      }
+      return { value: fromPkg, source: PACKAGE_JSON, warnings };
+    }
+    warnings.push(`could not read a repository from ${PACKAGE_JSON} ("${input.pkgRepository}")`);
+  }
+  if (fromGit)
+    return { value: fromGit, source: GIT_REMOTE, warnings };
+  return { value: undefined, warnings };
+}
+
 // src/resolve.ts
 var defaultResolveDeps = {
   resolveOrgAndProjectId,
   resolvePipelineDefinitionId,
-  log: (message) => console.error(message)
+  log: (message) => console.error(message),
+  env: process.env,
+  homedir: homedir(),
+  readFile: (path) => {
+    try {
+      return readFileSync(path, "utf8");
+    } catch {
+      return null;
+    }
+  },
+  cwd: process.cwd(),
+  gitRemoteUrl: () => {
+    const r = run("git", ["remote", "get-url", "origin"]);
+    return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : null;
+  }
 };
+function resolveMissingVcsOrigin(opts, deps) {
+  if (opts.vcsOrigin)
+    return opts.vcsOrigin;
+  let pkgRepository;
+  const pkgText = deps.readFile(join2(deps.cwd, "package.json"));
+  if (pkgText !== null) {
+    try {
+      pkgRepository = repositoryFromPackageJson(JSON.parse(pkgText).repository);
+    } catch {
+      deps.log("warning: could not parse package.json while looking for a repository");
+    }
+  }
+  const found = resolveVcsOrigin({ pkgRepository, gitRemote: deps.gitRemoteUrl() });
+  for (const w of found.warnings)
+    deps.log(`warning: ${w}`);
+  if (found.value === undefined) {
+    throw new Error("--vcs-origin is required for --provider circleci and could not be inferred " + "(looked in: package.json repository, git remote origin). Pass e.g. --vcs-origin github.com/org/repo.");
+  }
+  deps.log(`vcs-origin: ${found.value} (from ${found.source})`);
+  opts.vcsOrigin = found.value;
+  return found.value;
+}
 async function resolveCircleciOptions(parsed, deps = defaultResolveDeps) {
   const opts = parsed.options;
   if (opts.provider !== "circleci")
     return;
-  if (!opts.circleToken)
+  const vcsOrigin = resolveMissingVcsOrigin(opts, deps);
+  const missing = [
+    !opts.orgId && "--org-id",
+    !opts.projectId && "--project-id",
+    !opts.pipelineDefinitionId && "--pipeline-definition-id"
+  ].filter((m) => Boolean(m));
+  if (missing.length === 0)
     return;
-  if (!opts.orgId || !opts.projectId) {
-    deps.log("Resolving org-id and project-id via CircleCI API...");
-    const resolved = await deps.resolveOrgAndProjectId(opts.circleToken, opts.vcsOrigin);
-    opts.orgId ??= resolved.orgId;
-    opts.projectId ??= resolved.projectId;
+  const found = resolveCircleToken({
+    flag: opts.circleToken,
+    env: deps.env,
+    homedir: deps.homedir,
+    readFile: deps.readFile
+  });
+  for (const note of found.notes)
+    deps.log(`note: ${note}`);
+  if (found.token === undefined) {
+    throw new Error(`missing ${missing.join(", ")} for --provider circleci. Pass them explicitly, ` + `or provide a CircleCI API token so they can be resolved (looked in: ${TOKEN_SOURCES.join(", ")}).`);
   }
-  if (!opts.pipelineDefinitionId) {
-    deps.log("Resolving pipeline-definition-id via CircleCI API...");
-    opts.pipelineDefinitionId = await deps.resolvePipelineDefinitionId(opts.circleToken, opts.projectId, opts.file);
+  const { token, source } = found;
+  deps.log(`Using CircleCI token from ${source}`);
+  try {
+    if (!opts.orgId || !opts.projectId) {
+      deps.log("Resolving org-id and project-id via CircleCI API...");
+      const resolved = await deps.resolveOrgAndProjectId(token, vcsOrigin);
+      opts.orgId ??= resolved.orgId;
+      opts.projectId ??= resolved.projectId;
+    }
+    if (!opts.pipelineDefinitionId) {
+      deps.log("Resolving pipeline-definition-id via CircleCI API...");
+      opts.pipelineDefinitionId = await deps.resolvePipelineDefinitionId(token, opts.projectId, opts.file);
+    }
+  } catch (err) {
+    if (err instanceof CircleApiError && (err.status === 401 || err.status === 403)) {
+      throw new Error(`CircleCI rejected the token from ${source} (${err.status}). ` + `Pass a valid token with --circle-token or the CIRCLE_TOKEN environment variable.`);
+    }
+    throw err;
   }
 }
 
 // src/npm.ts
 var MIN_NODE = "22.14.0";
-var MIN_NPM = "11.5.1";
+var MIN_NPM = "11.15.0";
 function cmpVersion(a, b) {
   const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
   const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
@@ -337,7 +523,7 @@ function displayCommand(args) {
 }
 
 // src/workspace.ts
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync as readFileSync2 } from "node:fs";
 import path2 from "node:path";
 
 // src/glob.ts
@@ -480,7 +666,7 @@ function parsePnpmPackages(content) {
   return result;
 }
 function readJson(file) {
-  return JSON.parse(readFileSync(file, "utf8"));
+  return JSON.parse(readFileSync2(file, "utf8"));
 }
 function readJsonSafe(file) {
   try {
@@ -493,7 +679,7 @@ function readJsonSafe(file) {
 function detectPatterns(root) {
   const pnpmFile = path2.join(root, "pnpm-workspace.yaml");
   if (existsSync(pnpmFile)) {
-    const patterns = parsePnpmPackages(readFileSync(pnpmFile, "utf8"));
+    const patterns = parsePnpmPackages(readFileSync2(pnpmFile, "utf8"));
     if (patterns.length > 0)
       return { source: "pnpm-workspace.yaml", patterns };
   }
@@ -537,6 +723,9 @@ function discoverPackages(root) {
   const dirs = expandPatterns(root, patterns);
   const all = [];
   const seen = new Set;
+  if (existsSync(path2.join(root, "pnpm-workspace.yaml"))) {
+    dirs.unshift(path2.resolve(root));
+  }
   for (const dir of dirs) {
     const pkg = readPkg(dir);
     if (pkg && !seen.has(pkg.name)) {
@@ -564,7 +753,7 @@ function filterPackages(all, only, exclude) {
   });
 }
 // package.json
-var version = "0.2.2";
+var version = "0.3.1";
 
 // src/cli.ts
 var VERSION = version;
@@ -574,40 +763,57 @@ Usage:
   trustci [trust] --provider <github|gitlab|circleci> [provider flags] [options]
   trustci list [package] [--dry-run]
 
+Commands:
+  trust      register a trusted publisher for every public workspace package
+             (the default; "trust" may be omitted)
+  list       run \`npm trust list\` for <package>, or for every public workspace package
+
 Providers:
   github     --repo <owner/repo> --file <workflow> [--env <name>]
   gitlab     --project <group/project> --file <workflow> [--env <name>]
              (--repo is accepted as an alias for --project)
-  circleci   --vcs-origin <host/owner/repo> --circle-token <token> [--file <config>]
+  circleci   [--vcs-origin <host/owner/repo>] [--circle-token <token>] [--file <config>]
              [--org-id <uuid>] [--project-id <uuid>] [--pipeline-definition-id <uuid>]
              [--context-id <uuid> ...]
-             UUIDs are auto-resolved via CircleCI API v2 when --circle-token is provided.
-             Explicit UUIDs override auto-resolution and work without a token.
+             --vcs-origin defaults to the root package.json "repository", then
+             \`git remote get-url origin\`.
+             Missing UUIDs are resolved via CircleCI API v2 (also under --dry-run)
+             using a token from --circle-token, $CIRCLE_TOKEN, $CIRCLECI_TOKEN,
+             $CIRCLE_CLI_TOKEN, $CIRCLECI_CLI_TOKEN, or ~/.circleci/cli.yml (in that order).
+             Explicit UUIDs override auto-resolution; with all three, no token is needed.
+             --file selects the pipeline definition by config path or name (needed
+             when the project has more than one); it is not passed to npm trust.
 
 Permissions (at least one required):
   --allow-publish           allow npm publish
   --allow-stage-publish     allow npm stage publish
 
 Options:
-  --dry-run                 print the npm trust commands without executing them
+  --dry-run                 print the npm commands without executing them
   --only <name-glob>        only include packages matching (repeatable)
   --exclude <name-glob>     exclude packages matching (repeatable)
-  -y, --yes                 skip the confirmation prompt (and npm's)
+                            globs match the whole name; * also matches "/"
+  -y, --yes                 skip the confirmation prompt (and npm's);
+                            required when stdin is not a terminal
   -h, --help                show this help
   -v, --version             show the trustci version
 
 Workspaces are detected from pnpm-workspace.yaml, package.json "workspaces",
 or lerna.json. If no workspace config is found, the root package.json is used
 as a single-package fallback. Private packages ("private": true) are always excluded.
+On a real run, packages not yet published to the registry are skipped.
 
 Examples:
   trustci --dry-run --provider github --repo me/repo --file release.yml --allow-publish
   trustci --provider gitlab --project me/repo --file .gitlab-ci.yml --allow-publish -y
-  trustci --provider circleci --vcs-origin github.com/me/repo \\
-    --circle-token $CIRCLECI_TOKEN --allow-publish
+  CIRCLE_TOKEN=... trustci --provider circleci --allow-publish
+  trustci --provider circleci --file .circleci/config.yml --allow-publish
   trustci --provider circleci --org-id <uuid> --project-id <uuid> \\
     --pipeline-definition-id <uuid> --vcs-origin github.com/me/repo --allow-publish
   trustci list
+
+Requires npm >= 11.15.0 and Node >= 22.14.0.
+Documentation: https://trustci.hidetaka.dev
 `;
 async function confirm(question) {
   const rl = createInterface({ input: process2.stdin, output: process2.stderr });
@@ -655,6 +861,9 @@ async function runTrust(parsed) {
   const candidates = filterPackages(all, parsed.only, parsed.exclude);
   if (candidates.length === 0) {
     console.error(`No public packages matched (out of ${all.length} discovered via ${source}).`);
+    for (const pkg of all) {
+      console.error(`  - ${pkg.name}${pkg.private ? " (private)" : ""}`);
+    }
     return 1;
   }
   console.error(`Detected ${all.length} package(s) via ${source}; ${candidates.length} public after filters.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trustci",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Bulk-register npm Trusted Publishers (npm trust) across all public packages in a monorepo. Supports GitHub, GitLab and CircleCI.",
   "type": "module",
   "bin": {
@@ -11,7 +11,7 @@
   ],
   "engines": {
     "node": ">=22.14.0",
-    "npm": ">=11.5.1"
+    "npm": ">=11.15.0"
   },
   "scripts": {
     "build": "bun build src/cli.ts --target node --outfile dist/cli.js",