@bakit-org/ai-sdlc-cli 0.0.0-stage → 0.1.0

package/lib/github-checks.js

@@ -0,0 +1,43 @@
+'use strict';
+// Preflight checks for installing from the payload repository: which credential
+// source is available (never its value) and whether the repository is readable.
+// Each check is an async () => item | null, as the wizard's `extraChecks` expects.
+
+function githubChecks(client) {
+  let info = null;
+  const describe = async (signal) => {
+    info = info || (await client.describe({ signal }));
+    return info;
+  };
+
+  const tokenCheck = async ({ signal } = {}) => {
+    const { source, defaultBase, base } = await describe(signal);
+    if (source) return { id: 'github-token', status: 'ok', label: 'GitHub token', detail: `found via ${source}`, segment: 'github token' };
+    return {
+      id: 'github-token', status: 'fail', label: 'GitHub token',
+      detail: defaultBase
+        ? 'not found: set AI_SDLC_GITHUB_TOKEN, GH_TOKEN or GITHUB_TOKEN, run `gh auth login`, or configure a git credential helper; or pass --from-bundle <file>'
+        : `not found: ${base} needs AI_SDLC_GITHUB_TOKEN (other tokens are only used for the public GitHub API); or pass --from-bundle <file>`,
+      segment: 'github token: missing',
+    };
+  };
+
+  const accessCheck = async ({ signal } = {}) => {
+    const { repo, source } = await describe(signal);
+    if (!source) return null;
+    try {
+      await client.checkAccess({ signal });
+      return { id: 'github-access', status: 'ok', label: `Access to ${repo}`, detail: 'read access confirmed', segment: 'repo access' };
+    } catch (err) {
+      if (signal && signal.aborted) throw signal.reason;
+      const hint = err.message.includes('--from-bundle') ? '' : '; or pass --from-bundle <file> to use a local bundle';
+      return {
+        id: 'github-access', status: 'fail', label: `Access to ${repo}`, detail: `${err.message}${hint}`, segment: 'repo access: failed',
+      };
+    }
+  };
+
+  return [tokenCheck, accessCheck];
+}
+
+module.exports = { githubChecks };

package/lib/github-errors.js

@@ -0,0 +1,39 @@
+'use strict';
+// Turns a non-success GitHub response into a CliError with an actionable message.
+// Response bodies are never echoed: they are not needed and could carry request details.
+const { CliError } = require('./errors');
+const { OFFLINE_HINT } = require('./github-http');
+
+const header = (res, name) => (res.headers && res.headers.get(name)) || '';
+
+function resetText(res) {
+  const epoch = Number(header(res, 'x-ratelimit-reset'));
+  if (Number.isFinite(epoch) && epoch > 0) return `resets at ${new Date(epoch * 1000).toISOString().replace('T', ' ').slice(0, 16)} UTC`;
+  const wait = Number(header(res, 'retry-after'));
+  if (Number.isFinite(wait) && wait > 0) return `try again in ${Math.ceil(wait)}s`;
+  return 'try again later';
+}
+
+const isRateLimited = (res) => res.status === 429 || (res.status === 403 && (header(res, 'x-ratelimit-remaining') === '0' || header(res, 'retry-after') !== ''));
+
+function failureFor(res, { repo, source, notFound }) {
+  if (res.status === 401) {
+    return new CliError(`GitHub rejected the token from ${source} (invalid or expired); renew it, or run \`gh auth login\` and try again`);
+  }
+  if (res.status === 403 && header(res, 'x-github-sso')) {
+    return new CliError(`${repo} sits behind SAML single sign-on: authorize the token for the organization (GitHub: Settings > Developer settings > Personal access tokens > Configure SSO), then try again`);
+  }
+  if (isRateLimited(res)) return new CliError(`GitHub rate limit reached; ${resetText(res)}. Use --from-bundle <file> to install without GitHub`);
+  if (res.status === 404 && notFound) {
+    const err = new CliError(notFound);
+    err.kind = 'not-found';
+    return err;
+  }
+  if (res.status === 403 || res.status === 404) {
+    return new CliError(`no read access to ${repo} — ask the repo owner to grant read access: https://github.com/${repo} (or install from a local file with --from-bundle <file>)`);
+  }
+  if (res.status >= 500) return new CliError(`GitHub is unavailable (HTTP ${res.status}); try again later. ${OFFLINE_HINT}`);
+  return new CliError(`unexpected response from GitHub (HTTP ${res.status})`);
+}
+
+module.exports = { failureFor };

package/lib/github-http.js

@@ -0,0 +1,107 @@
+'use strict';
+// One HTTP request against the GitHub API with timeouts, retries and manual
+// redirect handling. The Authorization header goes only to the API origin: an
+// asset download that redirects to a storage host is fetched without it.
+const { CliError } = require('./errors');
+const { isAllowedUrl } = require('./config');
+
+const MAX_REDIRECTS = 5;
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+const OFFLINE_HINT = 'check your network, or install from a local file with --from-bundle <file>';
+
+// Sleeps, but wakes early (rejecting with the signal's reason) when the signal aborts.
+function sleepMs(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal && signal.aborted) return reject(signal.reason);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    if (signal) signal.addEventListener('abort', onAbort, { once: true });
+    return undefined;
+  });
+}
+
+class NetworkError extends Error {}
+
+async function readCapped(res, maxBytes) {
+  const declared = Number(res.headers.get('content-length'));
+  if (declared > maxBytes) throw new CliError(`GitHub response is larger than the ${maxBytes} byte limit`);
+  const chunks = [];
+  let total = 0;
+  if (res.body) {
+    for await (const chunk of res.body) {
+      total += chunk.length;
+      if (total > maxBytes) throw new CliError(`GitHub response is larger than the ${maxBytes} byte limit`);
+      chunks.push(chunk);
+    }
+  }
+  return Buffer.concat(chunks);
+}
+
+// A single attempt, following redirects by hand.
+async function attempt(startUrl, o, signal) {
+  const base = new URL(o.apiBase);
+  let url = new URL(startUrl);
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+    const headers = { 'User-Agent': 'ai-sdlc-cli', Accept: o.accept };
+    if (url.origin === base.origin) {
+      headers['X-GitHub-Api-Version'] = '2022-11-28';
+      if (o.token) headers.Authorization = `Bearer ${o.token}`;
+    }
+    const res = await o.fetchImpl(url, { redirect: 'manual', headers, signal });
+    if (!REDIRECTS.has(res.status)) return { status: res.status, headers: res.headers, body: await readCapped(res, o.maxBytes) };
+    const location = res.headers.get('location');
+    if (res.body) await res.body.cancel().catch(() => {});
+    if (!location) throw new CliError('GitHub sent a redirect without a target');
+    url = new URL(location, url);
+    if (!isAllowedUrl(url, o.apiBase)) throw new CliError(`refusing to follow a redirect to an unsafe address (${url.protocol}//${url.host})`);
+  }
+  throw new CliError('too many redirects from GitHub');
+}
+
+function networkMessage(err, timedOut, host, timeoutMs) {
+  if (timedOut) return `request to ${host} timed out after ${timeoutMs >= 1000 ? `${Math.round(timeoutMs / 1000)}s` : `${timeoutMs}ms`}; ${OFFLINE_HINT}`;
+  const code = (err && err.cause && err.cause.code) || (err && err.code);
+  return `cannot reach ${host}${typeof code === 'string' ? ` (${code})` : ''}; ${OFFLINE_HINT}`;
+}
+
+// Resolves { status, headers, body } for any final response (4xx included).
+// Network errors, timeouts and 5xx are retried `retries` times with backoff.
+async function request(url, options) {
+  const o = {
+    accept: 'application/vnd.github+json', fetchImpl: globalThis.fetch, timeoutMs: 20000, retries: 2, backoffMs: 400, maxBytes: 5 * 1024 * 1024,
+    ...Object.fromEntries(Object.entries(options).filter(([, v]) => v !== undefined)),
+  };
+  if (typeof o.fetchImpl !== 'function') throw new CliError('this Node.js has no fetch; Node 18 or newer is required');
+  const host = new URL(url).host;
+  let last;
+  for (let n = 0; n <= o.retries; n += 1) {
+    if (n > 0) await sleepMs(o.backoffMs * 2 ** (n - 1), o.signal);
+    if (o.signal && o.signal.aborted) throw o.signal.reason;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), o.timeoutMs);
+    const onCancel = () => controller.abort();
+    if (o.signal) o.signal.addEventListener('abort', onCancel, { once: true });
+    try {
+      const res = await attempt(url, o, controller.signal);
+      if (res.status < 500 || n === o.retries) return res;
+      last = res;
+    } catch (err) {
+      if (o.signal && o.signal.aborted) throw o.signal.reason;
+      if (err instanceof CliError) throw err;
+      last = new NetworkError(networkMessage(err, controller.signal.aborted, host, o.timeoutMs));
+      if (n === o.retries) throw new CliError(last.message);
+    } finally {
+      clearTimeout(timer);
+      if (o.signal) o.signal.removeEventListener('abort', onCancel);
+    }
+  }
+  return last;
+}
+
+module.exports = { request, OFFLINE_HINT };

package/lib/github-release.js

@@ -0,0 +1,156 @@
+'use strict';
+// Reads release bundles from the payload repository over the GitHub REST API
+// using the user's own credentials. Only Node's built-in fetch is used.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { CliError, UsageError } = require('./errors');
+const { payloadRepo, apiBase, isDefaultApiBase } = require('./config');
+const { resolveToken, redact, NO_TOKEN_MESSAGE, customBaseMessage } = require('./github-auth');
+const { onTermination } = require('./termination-cleanup');
+const { request } = require('./github-http');
+const { failureFor } = require('./github-errors');
+const semver = require('./semver');
+
+const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+const SAFE_NAME = /^[A-Za-z0-9._-]{1,200}$/;
+const OCTET = 'application/octet-stream';
+
+const stripV = (tag) => String(tag).replace(/^v/, '');
+
+// Candidate release tags for a requested version: as typed, then with/without the leading "v".
+function tagCandidates(version) {
+  const v = String(version).trim();
+  if (!semver.isReleaseTag(v)) throw new UsageError('--version must be a release version such as 1.2.0 or v1.2.0');
+  return [v, v.startsWith('v') ? v.slice(1) : `v${v}`];
+}
+
+// deps: { env, runCommand, fetchImpl, proc, releaseOptions: { timeoutMs, retries, backoffMs, tmpDir } }
+// Every method takes an optional { signal } (AbortSignal): aborting stops requests, backoff waits and child processes.
+function createGithubClient(deps = {}) {
+  const env = deps.env || process.env;
+  const proc = deps.proc || process;
+  const tuning = deps.releaseOptions || {};
+  let session = null;
+
+  // Token and endpoint, resolved once. Throws CliError when no credentials exist.
+  async function load(signal) {
+    if (!session) {
+      const repo = payloadRepo(env);
+      const base = apiBase(env);
+      const found = await resolveToken({ env, runCommand: deps.runCommand, signal, explicitOnly: !isDefaultApiBase(base) });
+      session = { repo, base, token: found ? found.token : null, source: found ? found.source : null };
+    }
+    return session;
+  }
+
+  async function connect(signal) {
+    const s = await load(signal);
+    if (!s.token) throw new CliError(isDefaultApiBase(s.base) ? NO_TOKEN_MESSAGE : customBaseMessage(s.base));
+    return s;
+  }
+
+  async function call(urlPath, { accept, maxBytes, notFound, signal } = {}) {
+    const s = await connect(signal);
+    let res;
+    try {
+      res = await request(`${s.base}${urlPath}`, {
+        token: s.token, apiBase: s.base, accept, maxBytes, signal, fetchImpl: deps.fetchImpl, ...tuning,
+      });
+    } catch (err) {
+      if (signal && signal.aborted) throw signal.reason;
+      // Whatever went wrong, the token must not travel with the message.
+      throw new CliError(redact(err.message, s.token), err instanceof CliError ? err.exitCode : 1);
+    }
+    if (res.status === 200) return res.body;
+    throw failureFor(res, { repo: s.repo, source: s.source, notFound });
+  }
+
+  const json = (buf, what) => {
+    try {
+      return JSON.parse(buf.toString('utf8'));
+    } catch {
+      throw new CliError(`GitHub sent an unreadable ${what}`);
+    }
+  };
+
+  async function checkAccess({ signal } = {}) {
+    const s = await connect(signal);
+    await call(`/repos/${s.repo}`, { signal });
+    return { repo: s.repo, source: s.source };
+  }
+
+  // The release for `version` (a tag) or the latest one.
+  async function findRelease(version, { signal } = {}) {
+    const tags = version ? tagCandidates(version) : [];
+    const s = await connect(signal);
+    const missing = (what) => `${what} in ${s.repo}`;
+    if (!version) {
+      return json(await call(`/repos/${s.repo}/releases/latest`, { signal, notFound: missing('no release has been published') }), 'release');
+    }
+    for (let i = 0; i < tags.length; i += 1) {
+      try {
+        return json(await call(`/repos/${s.repo}/releases/tags/${encodeURIComponent(tags[i])}`, { signal, notFound: missing(`release ${version} was not found`) }), 'release');
+      } catch (err) {
+        if (i === tags.length - 1 || err.kind !== 'not-found') throw err;
+      }
+    }
+    return null;
+  }
+
+  function pickAssets(release, repo) {
+    const tag = release && typeof release.tag_name === 'string' ? release.tag_name : '';
+    const assets = release && Array.isArray(release.assets) ? release.assets.filter((a) => a && SAFE_NAME.test(a.name || '') && Number.isInteger(a.id)) : [];
+    const bundles = assets.filter((a) => /^ai-sdlc-.+\.bundle\.json$/.test(a.name));
+    const bundle = bundles.find((a) => a.name === `ai-sdlc-${stripV(tag)}.bundle.json`) || (bundles.length === 1 ? bundles[0] : null);
+    if (!tag || !bundle) throw new CliError(`release ${tag || '(unnamed)'} in ${repo} has no bundle asset (expected ai-sdlc-<version>.bundle.json)`);
+    const sidecar = assets.find((a) => a.name === `${bundle.name}.sha256`);
+    if (!sidecar) throw new CliError(`release ${tag} in ${repo} has no checksum asset (${bundle.name}.sha256); refusing to install unverified`);
+    return { tag, bundle, sidecar };
+  }
+
+  // Downloads bundle + checksum into a private temp directory. Returns { bundlePath, version, cleanup }.
+  // The directory is also removed if the process is stopped with SIGINT/SIGTERM before cleanup() runs.
+  async function downloadBundle(version, { signal } = {}) {
+    const s = await connect(signal);
+    const release = await findRelease(version, { signal });
+    const { tag, bundle, sidecar } = pickAssets(release, s.repo);
+    const asset = (a, maxBytes) => call(`/repos/${s.repo}/releases/assets/${a.id}`, { signal, accept: OCTET, maxBytes, notFound: `release asset ${a.name} could not be downloaded` });
+    const dir = fs.mkdtempSync(path.join(tuning.tmpDir || os.tmpdir(), 'ai-sdlc-dl-'));
+    const remove = () => fs.rmSync(dir, { recursive: true, force: true });
+    const off = onTermination(proc, remove);
+    const cleanup = () => {
+      off();
+      remove();
+    };
+    try {
+      const bundlePath = path.join(dir, bundle.name);
+      fs.writeFileSync(bundlePath, await asset(bundle, MAX_BUNDLE_BYTES), { mode: 0o600 });
+      fs.writeFileSync(`${bundlePath}.sha256`, await asset(sidecar, 4096), { mode: 0o600 });
+      return { bundlePath, version: stripV(tag), cleanup };
+    } catch (err) {
+      cleanup();
+      throw err;
+    }
+  }
+
+  // Where the credentials came from (never the value) and which repo/base is used; source is null when none were found.
+  async function describe({ signal } = {}) {
+    const s = await load(signal);
+    return { repo: s.repo, base: s.base, defaultBase: isDefaultApiBase(s.base), source: s.source };
+  }
+
+  return { checkAccess, findRelease, downloadBundle, describe };
+}
+
+// The `fetchLatestBundle` plug for release-source.js.
+const createReleaseFetcher = (deps) => {
+  const client = deps.client || createGithubClient(deps);
+  return async (opts = {}) => {
+    if (opts.version) tagCandidates(opts.version);
+    await client.checkAccess({ signal: opts.signal });
+    return client.downloadBundle(opts.version, { signal: opts.signal });
+  };
+};
+
+module.exports = { createGithubClient, createReleaseFetcher, stripV, tagCandidates };

package/lib/journal.js

@@ -0,0 +1,117 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { CliError } = require('./errors');
+const { JOURNAL_REL } = require('./path-rules');
+const { resolveInside, writeAtomic, pruneEmptyDirs, assertRelPath } = require('./fs-safe');
+
+// The journal doubles as the per-project run lock (created exclusively) and as
+// the recovery record: before applying, it holds the previous content of every
+// path the run will touch, so an interrupted run can be rolled back exactly.
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+function readJournal(abs) {
+  try {
+    const value = JSON.parse(fs.readFileSync(abs, 'utf8'));
+    return value && typeof value === 'object' ? value : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// entries: [{ path, before }] where before is base64 content or null (file did not exist).
+function checkEntries(entries) {
+  if (!Array.isArray(entries)) throw new CliError('the interrupted-run journal is unreadable; inspect it, delete it by hand, then re-run');
+  for (const e of entries) {
+    if (!e || typeof e.path !== 'string' || (e.before !== null && typeof e.before !== 'string')) {
+      throw new CliError('the interrupted-run journal has a malformed entry; inspect it, delete it by hand, then re-run');
+    }
+    assertRelPath(e.path, 'journal path');
+    if (e.path.toLowerCase().split('/').includes('.git')) throw new CliError('the interrupted-run journal points into .git; refusing to replay it');
+  }
+  return entries;
+}
+
+// Puts every entry back as it was, newest first. Returns a list of problems (empty when clean).
+function rollbackEntries(project, entries) {
+  const problems = [];
+  for (const e of [...entries].reverse()) {
+    try {
+      const abs = resolveInside(project, e.path);
+      if (e.before === null) {
+        try {
+          fs.rmSync(abs, { force: true });
+        } catch (err) {
+          if (err.code !== 'ENOTDIR') throw err; // a parent is a plain file, so nothing was ever created here
+        }
+        pruneEmptyDirs(project, path.dirname(abs));
+      } else writeAtomic(abs, Buffer.from(e.before, 'base64'));
+    } catch (err) {
+      problems.push(`${e.path}: ${err.message}`);
+    }
+  }
+  return problems;
+}
+
+function recoverStale(project, abs, force) {
+  const journal = readJournal(abs);
+  if (journal && pidAlive(journal.pid)) {
+    throw new CliError(`another ai-sdlc run (pid ${journal.pid}) is in progress in this project; wait for it to finish`);
+  }
+  if (!force) {
+    throw new CliError(`${JOURNAL_REL} found: an earlier run was interrupted. Run "ai-sdlc doctor", then retry with --force to roll its changes back`);
+  }
+  if (journal && journal.entries !== null && journal.entries !== undefined) {
+    const problems = rollbackEntries(project, checkEntries(journal.entries));
+    if (problems.length) throw new CliError(`rolling back the interrupted run failed: ${problems.join('; ')}`);
+  }
+  fs.rmSync(abs, { force: true });
+}
+
+// Takes the project lock for one mutating run. Throws if another run holds it,
+// or if a stale journal exists and `force` is not set (with force it is rolled back first).
+function acquireLock(project, op, { force = false } = {}) {
+  const abs = resolveInside(project, JOURNAL_REL);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  let fd;
+  for (let attempt = 0; attempt < 2 && fd === undefined; attempt += 1) {
+    try {
+      fd = fs.openSync(abs, 'wx');
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      recoverStale(project, abs, force);
+    }
+  }
+  if (fd === undefined) throw new CliError('could not take the project lock; another run is starting at the same time');
+  try {
+    fs.writeSync(fd, `${JSON.stringify({ op, pid: process.pid, entries: null })}\n`);
+  } finally {
+    fs.closeSync(fd);
+  }
+  let kept = false;
+  return {
+    record(entries) {
+      writeAtomic(abs, Buffer.from(`${JSON.stringify({ op, pid: process.pid, entries })}\n`));
+    },
+    // Leave the journal in place (a rollback failed and needs --force recovery).
+    keep() {
+      kept = true;
+    },
+    release() {
+      if (kept) return;
+      fs.rmSync(abs, { force: true });
+      pruneEmptyDirs(project, path.dirname(abs));
+    },
+  };
+}
+
+module.exports = { acquireLock, rollbackEntries };

package/lib/manifest.js

@@ -0,0 +1,64 @@
+'use strict';
+const { CliError } = require('./errors');
+const { assertRelPath, inspect } = require('./fs-safe');
+const { MANIFEST_REL, JOURNAL_REL, installPathProblem } = require('./path-rules');
+const semver = require('./semver');
+
+const MANIFEST_SCHEMA = 1;
+
+function bad(why) {
+  throw new CliError(`installed manifest ${MANIFEST_REL} is invalid: ${why}`);
+}
+
+function validate(m) {
+  if (!m || typeof m !== 'object' || Array.isArray(m)) bad('not an object');
+  if (m.tool !== 'ai-sdlc-cli' || m.schema !== MANIFEST_SCHEMA) bad('unknown tool or schema');
+  if (!semver.isStrict(m.payload_version)) bad('payload_version is missing or not a version');
+  if (!Array.isArray(m.files)) bad('files missing');
+  for (const f of m.files) {
+    if (!f || (f.class !== 'managed' && f.class !== 'user-once') || !/^[0-9a-f]{64}$/.test(f.sha256 || '')) bad('bad file entry');
+    assertRelPath(f.path, 'manifest path');
+    const why = installPathProblem(f.path, f.class);
+    if (why) bad(`${f.path}: ${why}`);
+  }
+  if (!Array.isArray(m.hooks)) bad('hooks missing');
+  for (const h of m.hooks) {
+    if (!h || typeof h.event !== 'string' || typeof h.command !== 'string') bad('bad hook entry');
+  }
+  const b = m.block;
+  if (b !== null && (!b || typeof b.created !== 'boolean' || typeof b.prefix !== 'string' || typeof b.eol !== 'string')) bad('bad block record');
+  const s = m.settings;
+  if (s !== null && (!s || typeof s.created !== 'boolean' || (s.original !== null && typeof s.original !== 'string'))) bad('bad settings record');
+  return m;
+}
+
+// Returns null when the project has no manifest.
+function readManifest(project) {
+  const f = inspect(project, MANIFEST_REL);
+  if (!f.exists) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(f.bytes.toString('utf8'));
+  } catch (err) {
+    bad(`not JSON (${err.message})`);
+  }
+  return validate(parsed);
+}
+
+function buildManifest({ cliVersion, payloadVersion, payloadSchema, files, block, hooks, settings }) {
+  return {
+    tool: 'ai-sdlc-cli',
+    schema: MANIFEST_SCHEMA,
+    cli_version: cliVersion,
+    payload_version: payloadVersion,
+    payload_schema: payloadSchema,
+    files: [...files].sort((a, b) => (a.path < b.path ? -1 : 1)),
+    block: block || null,
+    hooks,
+    settings: settings || null,
+  };
+}
+
+const serializeManifest = (m) => Buffer.from(`${JSON.stringify(m, null, 2)}\n`, 'utf8');
+
+module.exports = { MANIFEST_REL, JOURNAL_REL, readManifest, buildManifest, serializeManifest };

package/lib/merge-claude-md.js

@@ -0,0 +1,63 @@
+'use strict';
+const { CliError } = require('./errors');
+
+const BEGIN = '<!-- ai-sdlc:begin -->';
+const END = '<!-- ai-sdlc:end -->';
+
+function findSpan(text) {
+  const b = text.indexOf(BEGIN);
+  const e = text.indexOf(END);
+  if (b === -1 && e === -1) return null;
+  if (b === -1 || e === -1 || e < b) {
+    throw new CliError('CLAUDE.md has an unbalanced ai-sdlc marker pair; fix it by hand and re-run. Nothing was changed.');
+  }
+  return { start: b, end: e + END.length };
+}
+
+const detectEol = (text) => (text.includes('\r\n') ? '\r\n' : '\n');
+
+function renderBlock(body, eol) {
+  const lines = body.replace(/\r\n/g, '\n').replace(/\n+$/, '').split('\n');
+  return [BEGIN, ...lines, END].join(eol);
+}
+
+// Inserts or refreshes the managed block. `info` is what an earlier call
+// returned; it records exactly the separator added so removal can restore the
+// original bytes. Returns { text, info }.
+function upsertBlock(current, body, info) {
+  if (current === null) {
+    return { text: `${renderBlock(body, '\n')}\n`, info: { created: true, prefix: '', eol: '\n' } };
+  }
+  const span = findSpan(current);
+  if (span) {
+    const eol = info ? info.eol : detectEol(current);
+    const text = current.slice(0, span.start) + renderBlock(body, eol) + current.slice(span.end);
+    return { text, info: info || { created: false, prefix: '', eol } };
+  }
+  const eol = detectEol(current);
+  let prefix = '';
+  if (current !== '') prefix = current.endsWith('\n') ? eol : eol + eol;
+  return {
+    text: `${current}${prefix}${renderBlock(body, eol)}${eol}`,
+    info: { created: false, prefix, eol },
+  };
+}
+
+// Strips the managed block. text === null means "the CLI created this file and
+// nothing else is in it, so delete it".
+function removeBlock(current, info) {
+  if (current === null) return { text: null, changed: false };
+  const span = findSpan(current);
+  if (!span) return { text: current, changed: false };
+  let { start, end } = span;
+  if (current.startsWith(info.eol, end)) end += info.eol.length;
+  if (info.prefix && current.slice(start - info.prefix.length, start) === info.prefix) start -= info.prefix.length;
+  const text = current.slice(0, start) + current.slice(end);
+  return { text: text === '' && info.created ? null : text, changed: true };
+}
+
+function hasBlock(current) {
+  return current !== null && findSpan(current) !== null;
+}
+
+module.exports = { BEGIN, END, upsertBlock, removeBlock, hasBlock };