helix-sdlc 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Capgemini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+---
+title: helix-sdlc
+description: Public launcher that signs in to the private Helix feed and runs the @helix-sdlc/helix installer.
+---
 
-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.
+## Overview
+
+`helix-sdlc` installs Helix, Capgemini's AI-native software development lifecycle, with one command. It signs you in to the private Azure Artifacts feed that hosts `@helix-sdlc/helix`, then runs that installer. You do not edit any `.npmrc` file.
+
+This package contains no Helix content. The Helix skills, agents, and rules stay on the private feed, and you need read access to that feed to install them. Members of the FS business unit (`DL FSSBU ALL FS`) and the Artifex users group (`GP US SG-Artifex-Users`) can read the feed. They do not ask for access: Azure DevOps admits them automatically the first time they sign in to the `FS-ABS-ATWORK` organization with their Capgemini work account. A group change can take up to 24 hours. Guest and personal accounts are not admitted.
+
+Node.js 22 or later is required.
+
+This package was named `create-helix-sdlc` before version 0.3.0.
+
+## Install Helix
+
+From your project root:
+
+```bash
+npx -y helix-sdlc@latest --harness claude
+```
+
+Use `--harness github` for GitHub Copilot, `--harness artifex` for Artifex, or `--harness all`. The `-y` option stops npx from asking "Ok to proceed?" before it downloads the launcher.
+
+## Update, inspect, or remove Helix
+
+Put the command before the options:
+
+```bash
+npx -y helix-sdlc@latest update
+npx -y helix-sdlc@latest status
+npx -y helix-sdlc@latest uninstall --harness claude
+```
+
+With no command, the launcher runs `init`. Every other argument goes to the `helix` installer unchanged, so `--harness`, `--dest`, `--dry-run`, `--force`, `--prune`, `--with-docs`, `--docs-dest`, `--json`, and `--offline` work as the `@helix-sdlc/helix` README describes. The launcher returns the installer's exit code: 0 for success, 1 for an error, and 2 when `init` or `update` left conflicts to merge.
+
+## Sign-in
+
+The launcher tries these credentials in order and uses the first one the feed accepts:
+
+1. The `HELIX_NPM_TOKEN` environment variable, holding a personal access token (PAT) or an Entra access token. Use this in CI. A value with the shape of a JWT (three dot-separated parts) is sent as a Bearer token; any other value is sent as a PAT.
+2. Your Azure CLI sign-in. If you have run `az login --allow-no-subscriptions --tenant 76a2ae5a-9f00-4f6b-95ed-5d33d77c4d61` with your Capgemini account, you are not asked for anything. The launcher always asks Azure CLI for a token from the Capgemini tenant.
+3. Browser sign-in with your Capgemini account, when it is enabled and you run the launcher in a terminal. The launcher opens your browser, you sign in, and the launcher receives a short-lived token on a `localhost` address. It does not save the token and does not ask for a refresh token. Browser sign-in is off until the Helix app registration is approved; to test a registration early, set `HELIX_CLIENT_ID` to its client ID.
+4. A PAT saved in your user `.npmrc` for the Helix feed, by an earlier run of the launcher or by the manual setup in the install guide.
+5. A prompt for a PAT. Create one with the Packaging (Read) scope at <https://dev.azure.com/FS-ABS-ATWORK/_usersSettings/tokens>, then paste it. Input is hidden. The launcher checks the token and offers to save it in your user `.npmrc` with owner-only permissions, so later runs do not ask again.
+
+The credential is passed to npm through environment variables for that run only. The launcher writes to your `.npmrc` only when you accept the offer in step 5, and it never writes to the project `.npmrc`.
+
+Members of the FS business unit (`DL FSSBU ALL FS`) and the Artifex users group (`GP US SG-Artifex-Users`) get feed access automatically the first time they use it. A group change can take up to 24 hours. The first feed call with your token admits you. You do not need to open Azure DevOps in a browser first.
+
+If the feed refuses your Azure CLI or browser sign-in token, the launcher tells you what to check. Admission can take up to 24 hours after you join one of these groups. Check that you signed in with your `@capgemini.com` work account, not a guest or personal account. If it still fails, contact the Helix team.
+
+On a machine with no browser, for example over SSH, browser sign-in cannot work, and Capgemini blocks the device code sign-in that would replace it. Use the Azure CLI or a PAT there.
+
+If the feed answers 404, the launcher says that the feed was not found. Check `HELIX_REGISTRY` if you set it, or contact the Helix team.
+
+## Launcher options
+
+| Flag                | Effect                                                                                                 |
+|---------------------|--------------------------------------------------------------------------------------------------------|
+| `--helix-version V` | Installs version `V` of `@helix-sdlc/helix` instead of `latest`.                                       |
+| `--pat`             | Asks for a PAT even when another credential works, for example to replace an expired saved token.     |
+| `--help`, `-h`      | Shows the launcher help. After a command (`init --help`), it shows the installer's help instead.       |
+
+## Licence
+
+MIT. See `LICENSE`.

package/bin/helix-sdlc.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Capgemini
+// SPDX-License-Identifier: MIT
+import { main } from '../lib/launcher.js';
+
+process.exitCode = await main(process.argv.slice(2));

package/lib/launcher.js

@@ -0,0 +1,485 @@
+// Copyright (c) 2026 Capgemini
+// SPDX-License-Identifier: MIT
+//
+// Public launcher for the private @helix-sdlc/helix installer. It finds a
+// credential for the org-scoped Helix feed, then runs the installer through
+// `npm exec` with the scope registry and credential passed as npm_config_*
+// environment variables, so no project or user .npmrc edit is needed. This
+// package ships no Helix content.
+
+import { execFile as nodeExecFile, spawn as nodeSpawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { Writable } from 'node:stream';
+
+export const PACKAGE = '@helix-sdlc/helix';
+export const ORG_URL = 'https://dev.azure.com/FS-ABS-ATWORK/';
+export const REGISTRY = 'https://pkgs.dev.azure.com/FS-ABS-ATWORK/_packaging/helix@Release/npm/registry/';
+/** Entra resource that Azure DevOps (and the feed) accepts for `az` tokens. */
+export const AZ_RESOURCE = 'https://app.vssps.visualstudio.com';
+/** Capgemini Entra tenant; pins `az` so a guest account in another tenant is not used. */
+export const TENANT = '76a2ae5a-9f00-4f6b-95ed-5d33d77c4d61';
+/** Basic-auth username for PATs. Azure Artifacts accepts any non-empty value. */
+export const AUTH_USER = 'helix';
+export const PAT_URL = `${ORG_URL}_usersSettings/tokens`;
+/**
+ * Entra public-client app for browser sign-in, registered by Group IT. Empty means browser sign-in
+ * is off; HELIX_CLIENT_ID overrides it for testing a new registration before a release.
+ */
+export const CLIENT_ID = '';
+const AUTHORITY = `https://login.microsoftonline.com/${TENANT}/oauth2/v2.0`;
+/** Azure DevOps only. No offline_access, so no refresh token is ever issued. */
+const SCOPE = '499b84ac-1321-427f-aa17-267ca6975798/.default';
+const COMMANDS = new Set(['init', 'update', 'status', 'uninstall']);
+const BLOCK_START = '; begin helix-sdlc feed auth';
+const BLOCK_END = '; end helix-sdlc feed auth';
+
+export const USAGE = `Usage: npx -y helix-sdlc@latest [command] [options]
+
+Signs in to the private Helix feed and runs ${PACKAGE}. With no command, runs init.
+
+Commands (passed to helix): init, update, status, uninstall
+Options (passed to helix):  --harness claude|github|artifex|all, --dest PATH,
+                            --dry-run, --force, --prune, --with-docs,
+                            --docs-dest PATH, --json, --offline
+Launcher options:
+  --helix-version V  Install this ${PACKAGE} version (default: latest).
+  --pat              Ask for a personal access token even when another
+                     credential is available, and offer to save it.
+  --help, -h         Show this help. Put it after a command (for example
+                     "init --help") to see helix's own help.
+
+Credentials are tried in this order:
+  1. HELIX_NPM_TOKEN environment variable (a PAT, or an Entra token; for CI)
+  2. Azure CLI sign-in: az login --allow-no-subscriptions --tenant ${TENANT}
+  3. Browser sign-in with your Capgemini account (when enabled)
+  4. A PAT saved in your user .npmrc by an earlier run
+  5. A prompt for a PAT with Packaging (Read) scope: ${PAT_URL}
+
+Members of DL FSSBU ALL FS and the Artifex users group get feed access
+automatically on first use. Group changes can take up to 24 hours.
+`;
+
+/** Splits launcher flags from the arguments forwarded to helix. */
+export function parseArgs(argv) {
+  const opts = { version: 'latest', pat: false, help: false };
+  const forward = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--helix-version') {
+      if (i + 1 >= argv.length) throw new Error('--helix-version needs a value');
+      opts.version = argv[++i];
+    } else if (a.startsWith('--helix-version=')) opts.version = a.slice('--helix-version='.length);
+    else if (a === '--pat') opts.pat = true;
+    else if ((a === '--help' || a === '-h') && !forward.some((f) => COMMANDS.has(f))) opts.help = true;
+    else forward.push(a);
+  }
+  if (!opts.version) throw new Error('--helix-version needs a value');
+  if (!forward.some((f) => COMMANDS.has(f))) forward.unshift('init');
+  return { opts, forward };
+}
+
+/** Registry URL without the scheme, as npm keys per-registry settings. */
+function registryKeys(registry) {
+  const noScheme = registry.replace(/^https?:/, '');
+  return [noScheme, noScheme.replace(/\/registry\/$/, '/')];
+}
+
+/** npm_config_* variables that point the scope at the feed and carry the credential. */
+export function npmEnv(credential, registry = REGISTRY) {
+  const env = { 'npm_config_@helix-sdlc:registry': registry };
+  if (!credential) return env;
+  for (const key of registryKeys(registry)) {
+    if (credential.type === 'bearer') env[`npm_config_${key}:_authToken`] = credential.token;
+    else {
+      env[`npm_config_${key}:username`] = AUTH_USER;
+      env[`npm_config_${key}:_password`] = Buffer.from(credential.token).toString('base64');
+      env[`npm_config_${key}:email`] = 'npm requires email to be set but does not use the value';
+    }
+  }
+  return env;
+}
+
+/** The user .npmrc path npm reads. */
+export function userConfigPath(env, homedir) {
+  return env.npm_config_userconfig || env.NPM_CONFIG_USERCONFIG || path.join(homedir, '.npmrc');
+}
+
+/** A PAT saved for the feed in a user .npmrc, or null. */
+export function savedPat(text, registry = REGISTRY) {
+  const key = `${registryKeys(registry)[0]}:_password`;
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.match(/^\s*([^=;#]+?)\s*=\s*(.*?)\s*$/);
+    if (m && m[1] === key && m[2]) return Buffer.from(m[2].replace(/^"|"$/g, ''), 'base64').toString('utf8');
+  }
+  return null;
+}
+
+/** Returns .npmrc text with the launcher's credential block added or replaced. */
+export function withSavedPat(text, pat, registry = REGISTRY) {
+  const encoded = Buffer.from(pat).toString('base64');
+  const lines = [BLOCK_START];
+  for (const key of registryKeys(registry)) {
+    lines.push(`${key}:username=${AUTH_USER}`, `${key}:_password=${encoded}`, `${key}:email=npm requires email to be set but does not use the value`);
+  }
+  lines.push(BLOCK_END);
+  const block = lines.join('\n');
+  const start = text.indexOf(BLOCK_START);
+  const end = text.indexOf(BLOCK_END);
+  if (start !== -1 && end > start) return text.slice(0, start) + block + text.slice(end + BLOCK_END.length);
+  const sep = text === '' || text.endsWith('\n') ? '' : '\n';
+  return `${text}${sep}${block}\n`;
+}
+
+function authHeader(credential) {
+  return credential.type === 'bearer'
+    ? `Bearer ${credential.token}`
+    : `Basic ${Buffer.from(`${AUTH_USER}:${credential.token}`).toString('base64')}`;
+}
+
+/** True for a JWT-shaped value (three base64url segments), which Azure DevOps takes as Bearer. */
+export function isJwt(token) {
+  return /^[\w-]+\.[\w-]+\.[\w-]+$/.test(token);
+}
+
+/** Checks a credential against the feed. Returns 'ok', 'unauthorized', 'forbidden', 'not-found', or 'error: ...'. */
+export async function probe(credential, { fetch, registry = REGISTRY }) {
+  try {
+    const res = await fetch(`${registry}${PACKAGE.replace('/', '%2f')}`, {
+      headers: { Authorization: authHeader(credential), Accept: 'application/json' },
+      signal: AbortSignal.timeout(15000),
+    });
+    if (res.ok) return 'ok';
+    if (res.status === 401) return 'unauthorized';
+    if (res.status === 403) return 'forbidden';
+    if (res.status === 404) return 'not-found';
+    return `error: HTTP ${res.status}`;
+  } catch (e) {
+    return `error: ${e.message}`;
+  }
+}
+
+/**
+ * Windows `.cmd` shims (az.cmd, npm.cmd) need cmd.exe. Passing an argument list with
+ * `shell: true` is deprecated (DEP0190), so run cmd.exe directly with one quoted command line.
+ * cmd.exe expands `%NAME%` even inside quotes and has no reliable escape, so `%` is rejected.
+ */
+export function winCommand(cmd, args) {
+  const bad = [cmd, ...args].find((a) => a.includes('%'));
+  if (bad !== undefined) {
+    throw new Error(`cannot pass "${bad}" through cmd.exe because it contains %. Use a path without %.`);
+  }
+  const quote = (a) => (/^[\w@+=:,./-]+$/.test(a) ? a : `"${a.replace(/"/g, '""')}"`);
+  return ['cmd.exe', ['/d', '/s', '/c', [cmd, ...args].map(quote).join(' ')]];
+}
+
+/** Best-effort `az account get-access-token`; resolves null when az is missing or signed out. */
+export function azToken({ execFile = nodeExecFile, platform = process.platform } = {}) {
+  return new Promise((resolve) => {
+    const args = ['account', 'get-access-token', '--resource', AZ_RESOURCE, '--tenant', TENANT, '--query', 'accessToken', '-o', 'tsv'];
+    const [file, argv] = platform === 'win32' ? winCommand('az', args) : ['az', args];
+    try {
+      execFile(
+        file,
+        argv,
+        { timeout: 30000, windowsHide: true },
+        (err, out) => resolve(err ? null : String(out).trim() || null),
+      );
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+/** Reads a line from the terminal without echoing it. */
+export function promptHidden(question, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve) => {
+    let muted = false;
+    const sink = new Writable({
+      write(chunk, _enc, cb) {
+        if (!muted) output.write(chunk);
+        cb();
+      },
+    });
+    const rl = readline.createInterface({ input, output: sink, terminal: true });
+    output.write(question);
+    muted = true;
+    rl.question('', (answer) => {
+      muted = false;
+      output.write('\n');
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/** Reads a visible line from the terminal. */
+export function promptLine(question, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input, output });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/** Opens a URL in the default browser, best effort. WSL uses the Windows browser. */
+export function openUrl(url, { spawn = nodeSpawn, platform = process.platform, env = process.env } = {}) {
+  let cmd;
+  let args;
+  if (platform === 'win32') [cmd, args] = ['rundll32', ['url.dll,FileProtocolHandler', url]];
+  else if (platform === 'darwin') [cmd, args] = ['open', [url]];
+  else if (env.WSL_DISTRO_NAME) [cmd, args] = ['powershell.exe', ['-NoProfile', '-Command', `Start-Process '${url}'`]];
+  else [cmd, args] = ['xdg-open', [url]];
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    // The URL is always printed, so a failed launch is not fatal.
+  }
+}
+
+/** Starts a one-shot loopback listener on 127.0.0.1 and, best effort, ::1 on the same port. */
+async function listenLoopback() {
+  const v4 = createServer();
+  await new Promise((ok, fail) => v4.once('error', fail).listen(0, '127.0.0.1', ok));
+  const servers = [v4];
+  const v6 = createServer();
+  await new Promise((ok) => v6.once('error', ok).listen(v4.address().port, '::1', () => (servers.push(v6), ok())));
+  return { port: v4.address().port, servers };
+}
+
+/**
+ * Signs in through the system browser with the authorization code flow and PKCE, and returns an
+ * Azure DevOps access token. Nothing is written to disk and no refresh token is requested.
+ */
+export async function browserToken({ clientId, openUrl, log, fetch = globalThis.fetch, timeoutMs = 300_000 }) {
+  const verifier = randomBytes(32).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  const state = randomBytes(16).toString('base64url');
+  const { port, servers } = await listenLoopback();
+  const redirectUri = `http://localhost:${port}/`;
+  try {
+    const code = await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('browser sign-in timed out')), timeoutMs);
+      const onRequest = (req, res) => {
+        const got = new URL(req.url, redirectUri).searchParams;
+        // Ignore favicon requests and anything else that is not the sign-in response.
+        if (!got.has('code') && !got.has('error')) {
+          res.writeHead(404).end();
+          return;
+        }
+        clearTimeout(timer);
+        const ok = got.get('state') === state && got.has('code');
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end(ok ? 'Helix sign-in is complete. You can close this tab.' : 'Helix sign-in failed. Return to the terminal for details.');
+        if (got.get('state') !== state) reject(new Error('browser sign-in response failed the state check'));
+        else if (got.has('error')) reject(new Error(`browser sign-in failed: ${got.get('error')} ${got.get('error_description') ?? ''}`.trim()));
+        else resolve(got.get('code'));
+      };
+      for (const s of servers) s.on('request', onRequest);
+      const url = `${AUTHORITY}/authorize?${new URLSearchParams({
+        client_id: clientId,
+        response_type: 'code',
+        response_mode: 'query',
+        redirect_uri: redirectUri,
+        scope: SCOPE,
+        state,
+        code_challenge: challenge,
+        code_challenge_method: 'S256',
+        prompt: 'select_account',
+        domain_hint: 'capgemini.com',
+      })}`;
+      log(`Opening your browser to sign in with your Capgemini account. If it does not open, visit:\n  ${url}`);
+      openUrl(url);
+    });
+    const res = await fetch(`${AUTHORITY}/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        client_id: clientId,
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: verifier,
+        scope: SCOPE,
+      }).toString(),
+      signal: AbortSignal.timeout(30_000),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok || body.token_type !== 'Bearer' || !body.access_token) {
+      throw new Error(`browser sign-in token request failed: ${body.error ?? `HTTP ${res.status}`}`);
+    }
+    return body.access_token;
+  } finally {
+    for (const s of servers) s.close();
+  }
+}
+
+const ADMISSION_HINT =
+  'You are signed in but cannot read the Helix feed yet. Members of the FS business unit (DL FSSBU ALL FS) ' +
+  'and the Artifex users group get access automatically the first time they use it. Group changes can take ' +
+  'up to 24 hours. Check that you signed in with your @capgemini.com work account, not a guest or personal ' +
+  'account. If it still fails, contact the Helix team.';
+const NOT_FOUND_HINT = (registry) =>
+  `The Helix feed was not found at ${registry}. If you set HELIX_REGISTRY, check its value. ` +
+  'Otherwise contact the Helix team.';
+
+/** Finds a credential the feed accepts. Returns { credential, source } or throws with guidance. */
+export async function resolveCredential(opts, deps) {
+  const { env, log, fetch, isTTY } = deps;
+  const notes = [];
+  let refused = false;
+  const tryCred = async (credential, source, { entra = false } = {}) => {
+    const r = await probe(credential, { fetch, registry: deps.registry });
+    if (r === 'ok') return { credential, source };
+    if (r === 'not-found') throw new Error(NOT_FOUND_HINT(deps.registry ?? REGISTRY));
+    if (r === 'forbidden') throw new Error(ADMISSION_HINT);
+    if (entra && r === 'unauthorized') refused = true;
+    notes.push(`${source}: ${r === 'unauthorized' ? 'rejected by the feed' : r}`);
+    return null;
+  };
+
+  if (env.HELIX_NPM_TOKEN) {
+    const token = env.HELIX_NPM_TOKEN;
+    const hit = await tryCred({ type: isJwt(token) ? 'bearer' : 'basic', token }, 'HELIX_NPM_TOKEN');
+    if (hit) return hit;
+    throw new Error('HELIX_NPM_TOKEN was rejected by the feed. Check that the token is valid and, for a PAT, has the Packaging (Read) scope.');
+  }
+
+  const rcPath = userConfigPath(env, deps.homedir);
+  const rcText = existsSync(rcPath) ? readFileSync(rcPath, 'utf8') : '';
+
+  if (!opts.pat) {
+    const token = await deps.azToken();
+    if (token) {
+      const hit = await tryCred({ type: 'bearer', token }, 'Azure CLI', { entra: true });
+      if (hit) return hit;
+    } else notes.push('Azure CLI: not installed or not signed in');
+
+    const clientId = env.HELIX_CLIENT_ID || deps.clientId;
+    if (clientId && isTTY) {
+      let token = null;
+      try {
+        token = await deps.browserToken({ clientId, log, fetch, openUrl: deps.openUrl });
+      } catch (e) {
+        notes.push(`Browser sign-in: ${e.message}`);
+      }
+      if (token) {
+        const hit = await tryCred({ type: 'bearer', token }, 'browser sign-in', { entra: true });
+        if (hit) return hit;
+      }
+    }
+
+    const pat = savedPat(rcText, deps.registry);
+    if (pat) {
+      const hit = await tryCred({ type: 'basic', token: pat }, `PAT saved in ${rcPath}`);
+      if (hit) return hit;
+    }
+  }
+
+  if (!isTTY) {
+    throw new Error(
+      `No working credential for the Helix feed (${notes.join('; ') || 'none found'}).\n` +
+        (refused ? `${ADMISSION_HINT}\n` : '') +
+        `Run "az login --allow-no-subscriptions --tenant ${TENANT}", or set HELIX_NPM_TOKEN to a PAT with the Packaging (Read) scope.`,
+    );
+  }
+
+  for (const n of notes) log(`  ${n}`);
+  if (refused) log(ADMISSION_HINT);
+  log(`Create a personal access token with the Packaging (Read) scope at:\n  ${PAT_URL}`);
+  const pat = await deps.promptHidden('Paste the token (input is hidden): ');
+  if (!pat) throw new Error('No token entered.');
+  const hit = await tryCred({ type: 'basic', token: pat }, 'Entered PAT');
+  if (!hit) throw new Error('The feed rejected that token. Check that it is valid and has the Packaging (Read) scope.');
+  const answer = await deps.promptLine(`Save the token in ${rcPath} so you are not asked again? [Y/n] `);
+  if (!/^n/i.test(answer)) {
+    writeFileSync(rcPath, withSavedPat(rcText, pat, deps.registry), { mode: 0o600 });
+    log(`Saved. Remove the "${BLOCK_START}" block from ${rcPath} to forget it.`);
+  }
+  return hit;
+}
+
+/** Locates npm-cli.js so npm can be run through the current node on every platform. */
+export function findNpmCli({ env, execPath = process.execPath }) {
+  const candidates = [];
+  if (env.npm_execpath) {
+    candidates.push(env.npm_execpath.replace(/npx-cli\.js$/, 'npm-cli.js'));
+  }
+  const nodeDir = path.dirname(execPath);
+  candidates.push(
+    path.join(nodeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  );
+  return candidates.find((c) => c.endsWith('npm-cli.js') && existsSync(c)) ?? null;
+}
+
+/** Runs helix through npm exec and resolves with its exit code. */
+export function runHelix(forward, opts, extraEnv, { env, spawn = nodeSpawn, platform = process.platform, execPath = process.execPath }) {
+  const npmArgs = ['exec', '--yes', `--package=${PACKAGE}@${opts.version}`, '--', 'helix', ...forward];
+  const npmCli = findNpmCli({ env, execPath });
+  const childEnv = { ...env, ...extraEnv };
+  const child = npmCli
+    ? spawn(execPath, [npmCli, ...npmArgs], { stdio: 'inherit', env: childEnv })
+    : spawn(...(platform === 'win32' ? winCommand('npm', npmArgs) : ['npm', npmArgs]), { stdio: 'inherit', env: childEnv });
+  return new Promise((resolve) => {
+    child.on('error', () => resolve(1));
+    child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+  });
+}
+
+/** CLI entry point. Returns the process exit code. */
+export async function main(argv, io = {}) {
+  const env = io.env ?? process.env;
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const log = (s) => stderr.write(`${s}\n`);
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (e) {
+    log(`helix-sdlc: ${e.message}`);
+    return 1;
+  }
+  if (parsed.opts.help) {
+    stdout.write(USAGE);
+    return 0;
+  }
+  const deps = {
+    env,
+    log,
+    registry: env.HELIX_REGISTRY || REGISTRY,
+    fetch: io.fetch ?? globalThis.fetch,
+    isTTY: io.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    homedir: io.homedir ?? os.homedir(),
+    azToken: io.azToken ?? (() => azToken()),
+    openUrl: io.openUrl ?? ((u) => openUrl(u)),
+    clientId: io.clientId ?? CLIENT_ID,
+    browserToken: io.browserToken ?? browserToken,
+    promptHidden: io.promptHidden ?? ((q) => promptHidden(q)),
+    promptLine: io.promptLine ?? ((q) => promptLine(q)),
+  };
+  let resolved;
+  try {
+    resolved = await resolveCredential(parsed.opts, deps);
+  } catch (e) {
+    log(`helix-sdlc: ${e.message}`);
+    return 1;
+  }
+  log(`helix-sdlc: using ${resolved.source} for the Helix feed`);
+  // HELIX_LAUNCHER makes helix's hints name this launcher instead of the helix bin.
+  const helixEnv = { ...npmEnv(resolved.credential, deps.registry), HELIX_LAUNCHER: 'helix-sdlc' };
+  try {
+    return await (io.runHelix ?? runHelix)(parsed.forward, parsed.opts, helixEnv, { env });
+  } catch (e) {
+    log(`helix-sdlc: ${e.message}`);
+    return 1;
+  }
+}

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "helix-sdlc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Signs in to the private Helix feed and runs the @helix-sdlc/helix installer. Contains no Helix content.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "helix-sdlc": "bin/helix-sdlc.js" },
+  "files": ["bin/", "lib/", "LICENSE", "README.md"],
+  "engines": { "node": ">=22" },
+  "scripts": { "test": "node --test \"test/**/*.test.js\"" },
+  "publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" }
+}