@voxgig/sdkgen 4.28.0 → 4.30.0

package/src/admin/npm-trust.ts

@@ -0,0 +1,408 @@
+/* Copyright (c) 2026 Voxgig Ltd, MIT License */
+
+import { spawnSync } from 'node:child_process'
+
+
+type Mode = 'setup' | 'check' | 'dry-run'
+
+type Publication = {
+  pkg: string
+  file: string
+}
+
+type TrustSpec = {
+  repository: string
+  publish: Publication[]
+  mode: Mode
+  replace: boolean
+  otp?: string
+}
+
+type TrustEntry = {
+  id?: string
+  type?: string
+  file?: string
+  repository?: string
+  environment?: string
+  permissions?: string[]
+}
+
+type Assessment = {
+  match?: TrustEntry
+  extra: TrustEntry[]
+}
+
+type NpmPort = {
+  list(pkg: string): TrustEntry[]
+  create(pkg: string, repository: string, file: string): void
+  revoke(pkg: string, id: string): void
+}
+
+
+const USAGE =
+  'usage: npm-trust --repository <owner/repo> ' +
+  '--publish <package>=<workflow.yml> [--publish ...] ' +
+  '[--check | --dry-run] [--replace] [--otp <code>]'
+
+const REPOSITORY_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/
+const WORKFLOW_RE = /^[A-Za-z0-9_.-]+\.ya?ml$/
+const PACKAGE_RE = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/
+
+
+function parseArgs(argv: string[]): TrustSpec {
+  const spec: TrustSpec = { repository: '', publish: [], mode: 'setup', replace: false }
+  const modes: Mode[] = []
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    const value = (): string => {
+      const v = argv[++i]
+      if (null == v || v.startsWith('--')) {
+        throw new Error(`${arg} needs a value\n${USAGE}`)
+      }
+      return v
+    }
+
+    if ('--repository' === arg) {
+      if ('' !== spec.repository) {
+        throw new Error('--repository is given twice; the generated script already names it')
+      }
+      spec.repository = value()
+    }
+    else if ('--publish' === arg) {
+      const v = value()
+      const eq = v.indexOf('=')
+      spec.publish.push({ pkg: v.slice(0, eq < 0 ? v.length : eq), file: eq < 0 ? '' : v.slice(eq + 1) })
+    }
+    else if ('--check' === arg || '--dry-run' === arg) {
+      modes.push(arg.slice(2) as Mode)
+    }
+    else if ('--replace' === arg) {
+      spec.replace = true
+    }
+    else if ('--otp' === arg) {
+      spec.otp = value()
+    }
+    else {
+      throw new Error(`unknown argument: ${arg}\n${USAGE}`)
+    }
+  }
+
+  if (1 < modes.length) {
+    throw new Error(`--check and --dry-run are alternatives\n${USAGE}`)
+  }
+  spec.mode = modes[0] || 'setup'
+
+  if ('check' === spec.mode && spec.replace) {
+    throw new Error('--check changes nothing, so it cannot --replace')
+  }
+  if (!REPOSITORY_RE.test(spec.repository)) {
+    throw new Error(`--repository must be owner/repo, got: ${spec.repository || '(none)'}\n${USAGE}`)
+  }
+  if (0 === spec.publish.length) {
+    throw new Error(`at least one --publish is required\n${USAGE}`)
+  }
+
+  const seen = new Set<string>()
+  for (const { pkg, file } of spec.publish) {
+    if (!PACKAGE_RE.test(pkg)) {
+      throw new Error(`not an npm package name: ${pkg}`)
+    }
+    if (!WORKFLOW_RE.test(file)) {
+      throw new Error(`${pkg}: the workflow must be a .yml file name, not a path, got: ${file || '(none)'}`)
+    }
+    if (seen.has(pkg)) {
+      throw new Error(`${pkg} is named twice`)
+    }
+    seen.add(pkg)
+  }
+
+  return spec
+}
+
+
+// `npm trust list --json` prints one pretty-printed object per configuration
+// rather than an array, so the objects are split out by brace depth.
+function parseTrustList(text: string): TrustEntry[] {
+  const src = text.trim()
+  if ('' === src) {
+    return []
+  }
+
+  try {
+    const whole = JSON.parse(src)
+    return Array.isArray(whole) ? whole : [whole]
+  }
+  catch {
+    // Not a single JSON value: fall through to the object stream.
+  }
+
+  const entries: TrustEntry[] = []
+  let depth = 0
+  let start = -1
+  let inString = false
+  let escaped = false
+
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i]
+    if (inString) {
+      if (escaped) {
+        escaped = false
+      }
+      else if ('\\' === c) {
+        escaped = true
+      }
+      else if ('"' === c) {
+        inString = false
+      }
+    }
+    else if ('"' === c) {
+      inString = true
+    }
+    else if ('{' === c) {
+      if (0 === depth) {
+        start = i
+      }
+      depth++
+    }
+    else if ('}' === c) {
+      depth--
+      if (0 === depth) {
+        entries.push(JSON.parse(src.slice(start, i + 1)))
+      }
+    }
+  }
+
+  if (0 !== depth) {
+    throw new Error('could not read the output of `npm trust list --json`')
+  }
+
+  return entries
+}
+
+
+// The generated workflows declare no GitHub environment, so a configuration
+// that names one would never match the job's OIDC token.
+function assess(pub: Publication, repository: string, entries: TrustEntry[]): Assessment {
+  const matches = (e: TrustEntry) =>
+    'github' === e.type &&
+    repository.toLowerCase() === String(e.repository || '').toLowerCase() &&
+    pub.file === e.file &&
+    null == e.environment &&
+    (null == e.permissions || e.permissions.includes('createPackage'))
+
+  const match = entries.find(matches)
+  return { match, extra: entries.filter((e) => e !== match) }
+}
+
+
+function describe(e: TrustEntry): string {
+  return [
+    e.type || '?',
+    e.repository || '?',
+    e.file || '?',
+    ...(null == e.environment ? [] : ['environment ' + e.environment]),
+    ...(null == e.permissions ? [] : ['[' + e.permissions.join(', ') + ']']),
+    ...(null == e.id ? [] : ['id ' + e.id]),
+  ].join(' ')
+}
+
+
+function trustCommand(repository: string, pub: Publication): string {
+  return `npm trust github ${pub.pkg} --repository ${repository} ` +
+    `--file ${pub.file} --allow-publish`
+}
+
+
+function run(spec: TrustSpec, npm: NpmPort, out: (line: string) => void): number {
+  if ('dry-run' === spec.mode) {
+    for (const pub of spec.publish) {
+      out(`${pub.pkg}: ${trustCommand(spec.repository, pub)}`)
+    }
+    if (spec.replace) {
+      out('--replace would also revoke any other trusted publisher of these packages.')
+    }
+    return 0
+  }
+
+  let drift = false
+
+  // Nothing is created beside a configuration this repository did not ask
+  // for, so a replacement revokes first and creates after.
+  for (const pub of spec.publish) {
+    const { match, extra } = assess(pub, spec.repository, npm.list(pub.pkg))
+    const wanted = `github ${spec.repository} ${pub.file}`
+
+    let kept = 0
+    for (const e of extra) {
+      if ('setup' === spec.mode && spec.replace && null != e.id) {
+        npm.revoke(pub.pkg, e.id)
+        out(`${pub.pkg}: revoked: ${describe(e)}`)
+      }
+      else {
+        kept++
+        out(`${pub.pkg}: also trusted, and not by this repository's workflows: ${describe(e)}` +
+          ('setup' === spec.mode ? ' (--replace revokes it)' : ''))
+      }
+    }
+
+    const create = null == match && 'setup' === spec.mode && 0 === kept
+    if (null != match) {
+      out(`${pub.pkg}: trusted: ${wanted}`)
+    }
+    else if (create) {
+      npm.create(pub.pkg, spec.repository, pub.file)
+      out(`${pub.pkg}: now trusted: ${wanted}`)
+    }
+    else {
+      out(`${pub.pkg}: NOT trusted: ${wanted}`)
+    }
+
+    drift = drift || 0 < kept || (null == match && !create)
+  }
+
+  return drift ? 1 : 0
+}
+
+
+function npmFailure(action: string, stderr: string): string {
+  if (/EOTP|one-time pass/i.test(stderr)) {
+    return `${action} needs a one-time password: run again with --otp <code>`
+  }
+  if (/E404|not found/i.test(stderr)) {
+    return `${action}: the package is not on npm yet. Publish its first version ` +
+      'by hand, then set up trusted publishing'
+  }
+  if (/E401|ENEEDAUTH/.test(stderr)) {
+    return `${action}: not logged in to npm with publish rights. Run \`npm login\` first`
+  }
+  return `${action} failed:\n${stderr.trim()}`
+}
+
+
+// An npm without the command still exits 0 from `npm trust --help`, printing
+// "Unknown command", so only the usage text tells a capable npm apart.
+function trustCapableNpm(): string[] {
+  const shell = 'win32' === process.platform
+  const probe = spawnSync('npm', ['trust', '--help'], { encoding: 'utf8', shell })
+  return /npm trust github/.test(String(probe.stdout || '') + String(probe.stderr || '')) ?
+    ['npm'] : ['npx', '--yes', 'npm@latest']
+}
+
+
+// A captured call has no terminal, so npm raises EOTP instead of prompting;
+// the mutating calls keep the terminal and can prompt.
+function npmPort(otp?: string): NpmPort {
+  const npm = trustCapableNpm()
+  const shell = 'win32' === process.platform
+  const otpArgs = null == otp ? [] : ['--otp', otp]
+
+  const call = (args: string[], capture: boolean): string => {
+    const res = spawnSync(npm[0], [...npm.slice(1), ...args, ...otpArgs], {
+      encoding: 'utf8',
+      stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+      shell,
+    })
+    if (null != res.error) {
+      throw new Error(`could not run ${npm[0]}: ${res.error.message}`)
+    }
+    if (0 !== res.status) {
+      throw new Error(npmFailure(`npm ${args.slice(0, 3).join(' ')}`, String(res.stderr || '')))
+    }
+    return String(res.stdout || '')
+  }
+
+  return {
+    list: (pkg) => parseTrustList(call(['trust', 'list', pkg, '--json'], true)),
+    create: (pkg, repository, file) => {
+      call(['trust', 'github', pkg, '--repository', repository,
+        '--file', file, '--allow-publish', '--yes'], false)
+    },
+    revoke: (pkg, id) => {
+      call(['trust', 'revoke', pkg, '--id=' + id], false)
+    },
+  }
+}
+
+
+function shellQuote(value: string): string {
+  return "'" + value.replace(/'/g, "'\\''") + "'"
+}
+
+
+// A null repository still writes the script, so one generated while the
+// repository was on github.com cannot outlive the move.
+function npmTrustScript(repository: string | null, publish: Publication[]): string {
+  if (null == repository) {
+    return `#!/usr/bin/env bash
+# Generated by @voxgig/sdkgen. npm trusts GitHub Actions only for a repository
+# on github.com, and this project's repository is elsewhere.
+echo 'npm trusted publishing needs the repository on github.com; see .sdk/PUBLISHING.md.' >&2
+exit 1
+`
+  }
+
+  const args = [
+    '--repository ' + shellQuote(repository),
+    ...publish.map((p) => '--publish ' + shellQuote(`${p.pkg}=${p.file}`)),
+    '"$@"',
+  ]
+  return `#!/usr/bin/env bash
+# Generated by @voxgig/sdkgen. Registers this repository's npm publish
+# workflows as trusted publishers; --check reports drift, --dry-run changes nothing.
+set -euo pipefail
+sdk_dir="$(cd -- "$(dirname -- "\${BASH_SOURCE[0]}")/.." && pwd)"
+trust="$sdk_dir/node_modules/@voxgig/sdkgen/dist/admin/npm-trust.js"
+if [[ ! -f "$trust" ]]; then
+  echo 'Install or update the .sdk dependencies to configure npm trusted publishing.' >&2
+  exit 1
+fi
+exec node "$trust" \\
+  ${args.join(' \\\n  ')}
+`
+}
+
+
+const OFFLINE: NpmPort = {
+  list() { throw new Error('--dry-run does not contact npm') },
+  create() { throw new Error('--dry-run does not contact npm') },
+  revoke() { throw new Error('--dry-run does not contact npm') },
+}
+
+
+function main(argv: string[]): number {
+  try {
+    const spec = parseArgs(argv)
+    const npm = 'dry-run' === spec.mode ? OFFLINE : npmPort(spec.otp)
+    return run(spec, npm, (line) => console.log(line))
+  }
+  catch (err: any) {
+    console.error(err.message)
+    return 2
+  }
+}
+
+
+if (require.main === module) {
+  process.exitCode = main(process.argv.slice(2))
+}
+
+
+export type {
+  Assessment,
+  NpmPort,
+  Publication,
+  TrustEntry,
+  TrustSpec,
+}
+
+export {
+  assess,
+  main,
+  npmFailure,
+  npmTrustScript,
+  parseArgs,
+  parseTrustList,
+  run,
+  trustCommand,
+}

package/src/cmp/PublishWorkflow.ts

@@ -9,6 +9,8 @@ import {
 
 import { packageName, packageVersion, repoInfo } from '../helpers/packageMeta'
 
+import { npmTrustScript } from '../admin/npm-trust'
+
 
 const PublishWorkflow = cmp(function PublishWorkflow(props: any) {
   const { ctx$ } = props
@@ -34,13 +36,15 @@ const PublishWorkflow = cmp(function PublishWorkflow(props: any) {
     return
   }
 
-  const { repoUrl } = repoInfo(model)
+  // npm trusts GitHub Actions only for a repository on github.com.
+  const { host, path } = repoInfo(model)
+  const repository = 'github.com' === host.toLowerCase() ? path : null
 
   Folder({ name: '.github' }, () => {
     Folder({ name: 'workflows' }, () => {
       for (const target of npmTargets) {
-        File({ name: `publish-${target.name}.yml` }, () => {
-          Content(publishWorkflow(model, target, npmTargets))
+        File({ name: workflowFile(target) }, () => {
+          Content(publishWorkflow(model, target, npmTargets, repository))
         })
       }
     })
@@ -48,7 +52,14 @@ const PublishWorkflow = cmp(function PublishWorkflow(props: any) {
 
   Folder({ name: '.sdk' }, () => {
     File({ name: 'PUBLISHING.md' }, () => {
-      Content(publishingDoc(model, npmTargets, repoUrl))
+      Content(publishingDoc(model, npmTargets, repository))
+    })
+
+    Folder({ name: 'admin' }, () => {
+      File({ name: 'setup-npm-trust.sh', mode: 0o755 }, () => {
+        Content(npmTrustScript(repository, npmTargets.map((t: any) =>
+          ({ pkg: packageName(model, t.name), file: workflowFile(t) }))))
+      })
     })
   })
 
@@ -59,6 +70,11 @@ const PublishWorkflow = cmp(function PublishWorkflow(props: any) {
 })
 
 
+function workflowFile(target: any): string {
+  return `publish-${target.name}.yml`
+}
+
+
 function isPrimaryNpm(model: any, target: any, npmTargets: any[]): boolean {
   if (1 === npmTargets.length) {
     return true
@@ -73,10 +89,16 @@ function releaseTag(model: any, target: any, npmTargets: any[]): string {
 }
 
 
-function publishWorkflow(model: any, target: any, npmTargets: any[]): string {
+function publishWorkflow(
+  model: any, target: any, npmTargets: any[], repository: string | null,
+): string {
   const name = target.name
   const tag = releaseTag(model, target, npmTargets)
   const pkg = packageName(model, name)
+  const setup = null == repository ? '' : `
+# .sdk/admin/setup-npm-trust.sh registers exactly this, and with --check
+# reports any drift from it.
+#`
 
   return `# Generated by @voxgig/sdkgen. Do not edit.
 #
@@ -88,10 +110,10 @@ function publishWorkflow(model: any, target: any, npmTargets: any[]): string {
 # SET UP ONCE, by a maintainer with publish rights — see .sdk/PUBLISHING.md:
 #
 #   npm trust github ${pkg} \\
-#     --repository <owner>/<repo> \\
-#     --file publish-${name}.yml \\
+#     --repository ${repository ?? '<owner>/<repo>'} \\
+#     --file ${workflowFile(target)} \\
 #     --allow-publish
-#
+#${setup}
 # THE FILENAME IS PART OF THAT CONFIGURATION. Renaming this file breaks
 # publishing until the npm side is updated to match.
 #
@@ -283,18 +305,27 @@ jobs:
 }
 
 
-function publishingDoc(model: any, targets: any[], repoUrl: string): string {
+function publishingDoc(model: any, targets: any[], repository: string | null): string {
   const pkg = packageName(model, targets[0].name)
-  const repo = String(repoUrl || '')
-    .replace(/^git\+/, '')
-    .replace(/^(https?:\/\/)?(www\.)?github\.com[/:]/, '')
-    .replace(/\.git$/, '')
-    .replace(/\/+$/, '')
-  const owner = '' === repo ? '<owner>/<repo>' : repo
+  const first = workflowFile(targets[0])
+
+  const setupHow = null == repository ? 'run:' :
+    'run\n`.sdk/admin/setup-npm-trust.sh`. It registers every workflow in the table\n' +
+    'above and leaves a package that is already set up alone; for the\n' +
+    `\`${targets[0].name}\` target it runs:`
+
+  const setupCheck = null == repository ? '' : `
+Run the script again with \`--check\` at any time. It compares what npm holds
+with what these workflows need, changes nothing, and exits non-zero on any
+difference, including a trusted publisher this repository did not ask for.
+\`--replace\` revokes those, \`--dry-run\` prints the commands without contacting
+npm, and \`--otp <code>\` hands npm a one-time password when it asks for one.
+An npm with no \`npm trust\` command is bypassed for \`npx npm@latest\`.
+`
 
   const rows = targets.map((t: any) =>
     `| \`${t.name}/\` | ${packageName(model, t.name)} | ` +
-    `\`.github/workflows/publish-${t.name}.yml\` |`).join('\n')
+    `\`.github/workflows/${workflowFile(t)}\` |`).join('\n')
 
   // WHICH TAG EACH TARGET CUTS. Worth a table rather than a sentence: the
   // primary npm target owns the bare `v<version>` and every other one is
@@ -332,7 +363,7 @@ publish credential, and attaches SLSA provenance as it goes.
 2. Commit and push to \`main\`, and let CI go green.
 3. Run the workflow from the Actions tab, or:
 
-       gh workflow run publish-${targets[0].name}.yml --ref main -f expect_sha=$(git rev-parse HEAD)
+       gh workflow run ${first} --ref main -f expect_sha=$(git rev-parse HEAD)
 
 \`expect_sha\` is optional and worth using: it refuses if \`main\` moved between
 the commit you checked and the run resolving.
@@ -363,21 +394,20 @@ its token into the git config for the whole job.
 
 ## One-time set-up
 
-npm has to be told which repository and which workflow file may publish this
+npm has to be told which repository and which workflow file may publish each
 package. From a machine logged in to npm with publish rights (2FA is
-required):
+required), ${setupHow}
 
     npm trust github ${pkg} \\
-      --repository ${owner} \\
-      --file publish-${targets[0].name}.yml \\
+      --repository ${repository ?? '<owner>/<repo>'} \\
+      --file ${first} \\
       --allow-publish
-
-Then \`npm trust list ${pkg}\` shows it, and
-\`npm trust revoke ${pkg} --id=<id>\` removes it.
+${setupCheck}
+\`npm trust list ${pkg}\` shows the configuration, and
+\`npm trust revoke ${pkg} --id=<id>\` removes one.
 
 **The workflow filename is part of the configuration.** Renaming
-\`publish-${targets[0].name}.yml\` breaks publishing until the npm side is
-updated to match.
+\`${first}\` breaks publishing until the npm side is updated to match.
 
 **A brand-new package cannot be set up this way.** npm only offers the
 trusted-publisher settings once a version exists, so the FIRST release of a

package/src/helpers/packageMeta.ts

@@ -33,6 +33,11 @@ function originName(model: any, target: string): string {
   return (null != orig && '' !== orig) ? String(orig) : target
 }
 
+function sdkName(slug: string): string {
+  return slug.endsWith('-sdk') ? slug : `${slug}-sdk`
+}
+
+
 function repoInfo(model: any) {
   const slug = model.name
   const origin = model.origin || 'voxgig-sdk'
@@ -40,7 +45,7 @@ function repoInfo(model: any) {
   const declared = (model && model.main && model.main[KIT] && model.main[KIT].repo) || {}
 
   const host = '' === (declared.host || '') ? 'github.com' : (declared.host || 'github.com')
-  const path = '' === (declared.path || '') ? `${origin}/${slug}-sdk` : String(declared.path)
+  const path = '' === (declared.path || '') ? `${origin}/${sdkName(slug)}` : String(declared.path)
 
   const seg = path.split('/')
   const repo = seg[seg.length - 1]
@@ -190,8 +195,8 @@ function apiName(model: any): string {
 function packageName(model: any, eco: string): string {
   const slug = model.name
   const origin = model.origin || 'voxgig-sdk'
-  const base = origin.endsWith('-sdk') ? slug : `${slug}-sdk`
-  const npmScoped = `@${origin}/${slug}${origin.endsWith('-sdk') ? '' : '-sdk'}`
+  const base = sdkName(slug)
+  const npmScoped = `@${origin}/${base}`
 
   const ECO_TARGET: Record<string, string> = {
     npm: 'ts', pypi: 'py', gem: 'rb', luarocks: 'lua', composer: 'php',
@@ -324,6 +329,7 @@ function envName(model: any): string {
 }
 
 export {
+  sdkName,
   PUBLISHER,
   PUBLISHER_URL,
   SECURITY_EMAIL,

package/src/sdkgen.ts

@@ -37,6 +37,7 @@ import { AgentGuideFeature } from './cmp/AgentGuideFeature'
 import { License } from './cmp/License'
 import { Security } from './cmp/Security'
 import { PublishWorkflow } from './cmp/PublishWorkflow'
+import { npmTrustScript } from './admin/npm-trust'
 import { Changelog } from './cmp/Changelog'
 import { Test } from './cmp/Test'
 import { TestControl, TEST_CONTROL_EXCLUDE } from './cmp/TestControl'
@@ -103,6 +104,7 @@ import {
 import type { Manifest, ManifestRead } from './helpers/manifest'
 import {
   packageName,
+  sdkName,
   installCommand,
   registryState,
   isPublished,
@@ -656,6 +658,8 @@ function externalItems(
 
         if (null != ov.path && '' !== ov.path) {
           output.path = ov.path
+          // The override relocates this run's output, root placement included.
+          delete output.root
         }
         if (null != ov.sdkrel && '' !== ov.sdkrel) {
           output.sdkrel = ov.sdkrel
@@ -718,6 +722,14 @@ function checkExternalFolders(external: ExternalPlan[], root: string, fs: any) {
       ext.target.output.path + '", which resolves to: ' + ext.folder +
       '\n  (SDK project: ' + root + ')'
 
+    if (true === ext.target.output.root) {
+      throw new SdkGenError(
+        label + ' "' + ext.name + '" declares both `output: path` and ' +
+        '`output: root: true`.\n  ' + where +
+        '\n  `path` generates it into another repository and `root` at the ' +
+        'root of this one. Keep one.')
+    }
+
     if (ext.folder === root || folderContains(root, ext.folder)) {
       throw new SdkGenError(
         'External output path is inside the SDK project.\n  ' + where +
@@ -945,6 +957,7 @@ export {
   License,
   Security,
   PublishWorkflow,
+  npmTrustScript,
   Changelog,
   Entity,
   Feature,
@@ -1094,6 +1107,7 @@ export {
   prefixLeadingDigit,
 
   packageName,
+  sdkName,
   installCommand,
   registryState,
   isPublished,