specrails-core 4.1.0 → 4.2.0

package/dist/installer/util/fs.js

@@ -0,0 +1,153 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { FilesystemError } from './errors.js';
+/**
+ * `mkdir -p` equivalent. Idempotent — no-op when `dir` already exists.
+ * Wraps filesystem errors as {@link FilesystemError} so callers get
+ * a typed exit code via the CLI dispatcher.
+ */
+export function mkdirp(dir) {
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        throw new FilesystemError(`failed to create directory: ${err.message}`, dir);
+    }
+}
+/**
+ * True when the path exists at all (file, directory, symlink, …).
+ */
+export function pathExists(p) {
+    return existsSync(p);
+}
+/**
+ * Writes `contents` to `filePath` after ensuring the parent directory
+ * exists and normalising line endings to LF. Normalisation rule:
+ * every `\r\n` → `\n`; lone `\r` left alone (very uncommon in our
+ * template inputs and more invasive to rewrite). Callers relying on
+ * strict LF-only output should pre-clean their strings.
+ */
+export function writeFileLf(filePath, contents) {
+    const parent = path.dirname(filePath);
+    mkdirp(parent);
+    const lf = contents.replace(/\r\n/g, '\n');
+    try {
+        writeFileSync(filePath, lf, { encoding: 'utf8' });
+    }
+    catch (err) {
+        throw new FilesystemError(`failed to write file: ${err.message}`, filePath);
+    }
+}
+/**
+ * Reads a UTF-8 text file. Wraps failures as {@link FilesystemError}.
+ */
+export function readTextFile(filePath) {
+    try {
+        return readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        throw new FilesystemError(`failed to read file: ${err.message}`, filePath);
+    }
+}
+/**
+ * Reads a file and returns its raw bytes. Used by the manifest hasher
+ * to avoid UTF-8 re-encoding round trips.
+ */
+export function readBytes(filePath) {
+    try {
+        return readFileSync(filePath);
+    }
+    catch (err) {
+        throw new FilesystemError(`failed to read file: ${err.message}`, filePath);
+    }
+}
+/**
+ * Copies a single file, ensuring the destination directory exists.
+ */
+export function copyFile(src, dest) {
+    mkdirp(path.dirname(dest));
+    try {
+        cpSync(src, dest);
+    }
+    catch (err) {
+        throw new FilesystemError(`failed to copy ${src} → ${dest}: ${err.message}`, dest);
+    }
+}
+/**
+ * Recursively copies a directory. Overwrites existing files by default.
+ * Honours a `filter(src, relPath)` predicate — returning false skips
+ * the entry (and, if it's a directory, its subtree).
+ */
+export function copyDir(srcDir, destDir, options = {}) {
+    if (!pathExists(srcDir)) {
+        throw new FilesystemError(`source directory does not exist`, srcDir);
+    }
+    mkdirp(destDir);
+    const walk = (currentSrc, currentDest, relPrefix) => {
+        let entries;
+        try {
+            entries = readdirSync(currentSrc);
+        }
+        catch (err) {
+            throw new FilesystemError(`failed to read directory: ${err.message}`, currentSrc);
+        }
+        for (const name of entries) {
+            const absSrc = path.join(currentSrc, name);
+            const absDest = path.join(currentDest, name);
+            const relPath = relPrefix === '' ? name : path.join(relPrefix, name);
+            if (options.filter && !options.filter(absSrc, relPath))
+                continue;
+            const st = statSync(absSrc);
+            if (st.isDirectory()) {
+                mkdirp(absDest);
+                walk(absSrc, absDest, relPath);
+            }
+            else if (st.isFile()) {
+                copyFile(absSrc, absDest);
+            }
+            // Other inode types (symlinks, sockets, …) intentionally skipped.
+        }
+    };
+    walk(srcDir, destDir, '');
+}
+/**
+ * Lists the immediate entries (files + directories) of `dir`. Returns
+ * absolute paths. Empty array when `dir` does not exist.
+ */
+export function listDir(dir) {
+    if (!pathExists(dir))
+        return [];
+    try {
+        return readdirSync(dir).map((name) => path.join(dir, name));
+    }
+    catch (err) {
+        throw new FilesystemError(`failed to list directory: ${err.message}`, dir);
+    }
+}
+/**
+ * True when the target path exists and resolves to a regular file.
+ */
+export function isFile(p) {
+    if (!pathExists(p))
+        return false;
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when the target path exists and resolves to a directory.
+ */
+export function isDir(p) {
+    if (!pathExists(p))
+        return false;
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/installer/util/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../../src/installer/util/fs.ts"],"names":[],"mappings":"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"}

package/dist/installer/util/git.js

@@ -0,0 +1,113 @@
+import { GitError } from './errors.js';
+import { runCommand } from './exec.js';
+/**
+ * Low-level git wrapper. Every method shells out to the user's `git`
+ * binary (already a prerequisite — the installer refuses to run
+ * without a git repo). Failures surface as {@link GitError} so the
+ * CLI dispatcher translates them to exit code 30.
+ *
+ * We intentionally keep the surface minimal (the six operations used
+ * by the installer) rather than wrapping `simple-git` — that package
+ * is ~100 KB and wraps the same shell-out we do here.
+ */
+export async function isGitRepo(cwd) {
+    try {
+        await runCommand('git', ['rev-parse', '--is-inside-work-tree'], {
+            cwd,
+            inherit: false,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns the absolute path of the repository root containing `cwd`.
+ * Throws {@link GitError} if `cwd` is not inside a git repo.
+ */
+export async function repoRoot(cwd) {
+    try {
+        const { stdout } = await runCommand('git', ['rev-parse', '--show-toplevel'], {
+            cwd,
+            inherit: false,
+        });
+        return stdout.trim();
+    }
+    catch (err) {
+        throw new GitError(`not a git repository (or parent directories): ${cwd}`, 'git rev-parse --show-toplevel');
+    }
+}
+/**
+ * Initialises a new git repository at `cwd` with an initial commit on
+ * the default branch name. Idempotent — no-op when `cwd` is already
+ * a repo.
+ */
+export async function initRepo(cwd) {
+    if (await isGitRepo(cwd))
+        return;
+    try {
+        await runCommand('git', ['init', '--initial-branch=main'], {
+            cwd,
+            inherit: false,
+        });
+    }
+    catch (err) {
+        // Older git versions (< 2.28) lack --initial-branch. Retry without.
+        await runCommand('git', ['init'], { cwd, inherit: false });
+    }
+}
+/**
+ * Porcelain working-tree status. Returns the raw short-format output
+ * (empty string when the tree is clean).
+ */
+export async function status(cwd) {
+    const { stdout } = await runCommand('git', ['status', '--porcelain'], {
+        cwd,
+        inherit: false,
+    });
+    return stdout;
+}
+/**
+ * Stages the given pathspecs. Empty array stages nothing and returns
+ * without invoking git.
+ */
+export async function add(cwd, pathspecs) {
+    if (pathspecs.length === 0)
+        return;
+    try {
+        await runCommand('git', ['add', '--', ...pathspecs], { cwd, inherit: false });
+    }
+    catch (err) {
+        throw new GitError(`failed to stage paths: ${pathspecs.join(', ')}`, `git add -- ${pathspecs.join(' ')}`);
+    }
+}
+/**
+ * Creates a commit with the given message using the committer identity
+ * currently configured on the repo / globally. Does NOT attempt to
+ * install an identity — that is a prerequisite check.
+ */
+export async function commit(cwd, message, opts = {}) {
+    const args = ['commit', '-m', message];
+    if (opts.allowEmpty)
+        args.push('--allow-empty');
+    try {
+        await runCommand('git', args, { cwd, inherit: false });
+    }
+    catch (err) {
+        throw new GitError(`git commit failed: ${err.message}`, `git ${args.join(' ')}`);
+    }
+}
+/**
+ * True when git is installed and on PATH.
+ */
+export async function gitInstalled() {
+    try {
+        await runCommand('git', ['--version'], { inherit: false });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/installer/util/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../../src/installer/util/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAEtC;;;;;;;;;GASG;AAEH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW;IACzC,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,uBAAuB,CAAC,EAAE;YAC9D,GAAG;YACH,OAAO,EAAE,KAAK;SACf,CAAC,CAAA;QACF,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAW;IACxC,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,iBAAiB,CAAC,EAAE;YAC3E,GAAG;YACH,OAAO,EAAE,KAAK;SACf,CAAC,CAAA;QACF,OAAO,MAAM,CAAC,IAAI,EAAE,CAAA;IACtB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAChB,iDAAiD,GAAG,EAAE,EACtD,+BAA+B,CAChC,CAAA;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAW;IACxC,IAAI,MAAM,SAAS,CAAC,GAAG,CAAC;QAAE,OAAM;IAChC,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,uBAAuB,CAAC,EAAE;YACzD,GAAG;YACH,OAAO,EAAE,KAAK;SACf,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,oEAAoE;QACpE,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;IAC5D,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,GAAW;IACtC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE;QACpE,GAAG;QACH,OAAO,EAAE,KAAK;KACf,CAAC,CAAA;IACF,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,GAAW,EAAE,SAAmB;IACxD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAM;IAClC,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;IAC/E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAChB,0BAA0B,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAChD,cAAc,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CACpC,CAAA;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,GAAW,EACX,OAAe,EACf,OAAiC,EAAE;IAEnC,MAAM,IAAI,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IACtC,IAAI,IAAI,CAAC,UAAU;QAAE,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;IAC/C,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;IACxD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAChB,sBAAuB,GAAa,CAAC,OAAO,EAAE,EAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CACxB,CAAA;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;QAC1D,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC"}

package/dist/installer/util/logger.js

@@ -0,0 +1,55 @@
+import pc from 'picocolors';
+let streams = {
+    out: process.stdout,
+    err: process.stderr,
+};
+export function setLoggerStreams(next) {
+    streams = { ...streams, ...next };
+}
+/** Restore logger to process.stdout/stderr. */
+export function resetLoggerStreams() {
+    streams = { out: process.stdout, err: process.stderr };
+}
+function writeOut(line) {
+    streams.out.write(line + '\n');
+}
+function writeErr(line) {
+    streams.err.write(line + '\n');
+}
+/** Section heading — bold, no prefix, leading blank line. */
+export function step(title) {
+    writeOut('');
+    writeOut(pc.bold(title));
+}
+/** Success line. Prefix: `  ✓ ` in green. */
+export function ok(msg) {
+    writeOut(`  ${pc.green('✓')} ${msg}`);
+}
+/** Warning line. Prefix: `  ⚠ ` in yellow. */
+export function warn(msg) {
+    writeOut(`  ${pc.yellow('⚠')} ${msg}`);
+}
+/** Failure line, routed to stderr. Prefix: `  ✗ ` in red. */
+export function fail(msg) {
+    writeErr(`  ${pc.red('✗')} ${msg}`);
+}
+/** Info line. Prefix: `  → ` in blue. */
+export function info(msg) {
+    writeOut(`  ${pc.blue('→')} ${msg}`);
+}
+/** Print a fatal error and its hint, routed to stderr. */
+export function fatal(message, hint) {
+    writeErr('');
+    writeErr(pc.red(pc.bold(`✗ ${message}`)));
+    if (hint) {
+        writeErr(pc.dim(`  ${hint}`));
+    }
+}
+/** Primitive write for cases where the caller owns formatting. */
+export function rawOut(text) {
+    streams.out.write(text);
+}
+export function rawErr(text) {
+    streams.err.write(text);
+}
+//# sourceMappingURL=logger.js.map

package/dist/installer/util/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../src/installer/util/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAA;AAgB3B,IAAI,OAAO,GAAY;IACrB,GAAG,EAAE,OAAO,CAAC,MAAM;IACnB,GAAG,EAAE,OAAO,CAAC,MAAM;CACpB,CAAA;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAsB;IACrD,OAAO,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,IAAI,EAAE,CAAA;AACnC,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,kBAAkB;IAChC,OAAO,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,MAAM,EAAE,CAAA;AACxD,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAA;AAChC,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAA;AAChC,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,IAAI,CAAC,KAAa;IAChC,QAAQ,CAAC,EAAE,CAAC,CAAA;IACZ,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;AAC1B,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,EAAE,CAAC,GAAW;IAC5B,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,CAAA;AACvC,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,IAAI,CAAC,GAAW;IAC9B,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,CAAA;AACxC,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,IAAI,CAAC,GAAW;IAC9B,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,CAAA;AACrC,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,IAAI,CAAC,GAAW;IAC9B,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,CAAA;AACtC,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,IAAa;IAClD,QAAQ,CAAC,EAAE,CAAC,CAAA;IACZ,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,CAAA;IACzC,IAAI,IAAI,EAAE,CAAC;QACT,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAA;IAC/B,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC"}

package/dist/installer/util/paths.js

@@ -0,0 +1,66 @@
+import path from 'node:path';
+/**
+ * Paths the installer MUST NOT create, modify, or delete. These hold
+ * user / team state that survives re-runs (profile JSON authored by
+ * specrails-hub, custom agents authored by the user). Breaking this
+ * contract silently destroys user work.
+ *
+ * Audited by vitest spec `reserved-paths.test.ts`.
+ */
+export const RESERVED_PATHS = [
+    /**
+     * .specrails/profiles/** — project + hub-authored profile JSON.
+     * specrails-hub writes profile files here and expects them preserved
+     * across specrails-core updates.
+     */
+    '.specrails/profiles/',
+    /**
+     * .claude/agents/custom-*.md — user-authored custom agents, kept
+     * distinct from the bundled sr-* agents so updates never overwrite
+     * them.
+     */
+    '.claude/agents/custom-',
+];
+/**
+ * Returns true when a repo-relative path falls inside a reserved
+ * region. Accepts both POSIX (/) and Windows (\) separators; the
+ * check normalises internally so callers can pass a value straight
+ * from `path.relative()` without worrying about host platform.
+ */
+export function isReservedPath(relPath) {
+    const normalised = relPath.replace(/\\/g, '/');
+    for (const prefix of RESERVED_PATHS) {
+        if (normalised.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Joins segments and forces POSIX separators. Use when a generated
+ * string is destined for a cross-platform artefact (JSON manifest,
+ * YAML config) rather than the local filesystem.
+ */
+export function toPosix(...segments) {
+    return path.posix.join(...segments.map((s) => s.replace(/\\/g, '/')));
+}
+/**
+ * Joins segments using the host platform's separator. Use when the
+ * result goes directly to `fs.*` / `child_process.*` calls.
+ */
+export function toNative(...segments) {
+    return path.join(...segments);
+}
+/**
+ * Repository-relative representation of an absolute path. Returns a
+ * POSIX-style path so callers can store it in manifests without OS
+ * contamination. If `absPath` is outside `repoRoot`, returns the
+ * original absolute path unchanged (POSIX-normalised).
+ */
+export function repoRelative(repoRoot, absPath) {
+    const rel = path.relative(repoRoot, absPath);
+    if (rel.startsWith('..')) {
+        return absPath.replace(/\\/g, '/');
+    }
+    return rel.replace(/\\/g, '/');
+}
+//# sourceMappingURL=paths.js.map

package/dist/installer/util/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/installer/util/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B;;;;OAIG;IACH,sBAAsB;IAEtB;;;;OAIG;IACH,wBAAwB;CAChB,CAAA;AAEV;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IAC9C,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;QACpC,IAAI,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAA;IAChD,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,GAAG,QAAkB;IAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAA;AACvE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAG,QAAkB;IAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAA;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,OAAe;IAC5D,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IAC5C,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IACpC,CAAC;IACD,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;AAChC,CAAC"}

package/dist/installer/util/prompts.js

@@ -0,0 +1,49 @@
+import { confirm, input, select } from '@inquirer/prompts';
+import { PromptAbortError } from './errors.js';
+/**
+ * Thin wrappers over `@inquirer/prompts` that add:
+ *  - Non-TTY detection → throws {@link PromptAbortError} unless the
+ *    caller provided a default, matching the old bash behaviour of
+ *    "use the default and don't ask when piped".
+ *  - Consistent typing (`string`, `boolean`, `T`) across the call
+ *    sites so command handlers don't need to think about `undefined`.
+ */
+function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+export async function text(opts) {
+    if (!isInteractive()) {
+        if (opts.default === undefined) {
+            throw new PromptAbortError(`cannot prompt for "${opts.message}" in a non-interactive environment`);
+        }
+        return opts.default;
+    }
+    return input({
+        message: opts.message,
+        default: opts.default,
+        validate: opts.validate,
+    });
+}
+export async function confirmYesNo(opts) {
+    if (!isInteractive()) {
+        if (opts.default === undefined) {
+            throw new PromptAbortError(`cannot confirm "${opts.message}" in a non-interactive environment`);
+        }
+        return opts.default;
+    }
+    return confirm({ message: opts.message, default: opts.default });
+}
+export async function chooseOne(opts) {
+    if (!isInteractive()) {
+        if (opts.default === undefined) {
+            throw new PromptAbortError(`cannot present choices for "${opts.message}" in a non-interactive environment`);
+        }
+        return opts.default;
+    }
+    return select({
+        message: opts.message,
+        choices: opts.choices,
+        default: opts.default,
+    });
+}
+//# sourceMappingURL=prompts.js.map

package/dist/installer/util/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/installer/util/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9C;;;;;;;GAOG;AAEH,SAAS,aAAa;IACpB,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC7D,CAAC;AAUD,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAiB;IAC1C,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC;QACrB,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,gBAAgB,CACxB,sBAAsB,IAAI,CAAC,OAAO,oCAAoC,CACvE,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAA;IACrB,CAAC;IACD,OAAO,KAAK,CAAC;QACX,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,IAAI,CAAC,QAAsD;KACtE,CAAC,CAAA;AACJ,CAAC;AAOD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAoB;IACrD,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC;QACrB,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,gBAAgB,CACxB,mBAAmB,IAAI,CAAC,OAAO,oCAAoC,CACpE,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAA;IACrB,CAAC;IACD,OAAO,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;AAClE,CAAC;AAQD,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,IAAsB;IACvD,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC;QACrB,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,gBAAgB,CACxB,+BAA+B,IAAI,CAAC,OAAO,oCAAoC,CAChF,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAA;IACrB,CAAC;IACD,OAAO,MAAM,CAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAA;AACJ,CAAC"}

package/dist/installer/util/template.js

@@ -0,0 +1,60 @@
+/**
+ * Small in-house template renderer. Replaces the bash heredocs the
+ * retired install.sh / update.sh used to emit manifests and config
+ * files.
+ *
+ * Syntax (intentionally minimal):
+ *   ${VAR_NAME}                  — value interpolation
+ *   {{#if FLAG}}block{{/if}}     — conditional block, rendered when
+ *                                  FLAG is truthy in the context
+ *   {{#ifnot FLAG}}block{{/ifnot}} — conditional block when FLAG is falsy
+ *
+ * Nested blocks are NOT supported. If a template outgrows this
+ * capability we switch to mustache — but every heredoc we've audited
+ * fits inside these three forms.
+ */
+/**
+ * Renders `template` by evaluating its directives against `context`.
+ * Missing interpolation variables render as the empty string rather
+ * than throwing — the bash scripts behaved the same way (`${X:-}` in
+ * a heredoc). Unknown flags in an `{{#if}}` are treated as falsy.
+ */
+export function render(template, context) {
+    let out = template;
+    // 1. Handle conditionals first so their variables don't get
+    //    interpolated if the block is skipped.
+    out = renderConditionals(out, context);
+    // 2. Interpolate variables.
+    out = renderInterpolations(out, context);
+    return out;
+}
+function renderConditionals(input, context) {
+    const ifRegex = /{{#if\s+([A-Z0-9_]+)\s*}}([\s\S]*?){{\/if}}/g;
+    const ifnotRegex = /{{#ifnot\s+([A-Z0-9_]+)\s*}}([\s\S]*?){{\/ifnot}}/g;
+    let out = input;
+    out = out.replace(ifRegex, (_match, name, body) => {
+        return truthy(context[name]) ? body : '';
+    });
+    out = out.replace(ifnotRegex, (_match, name, body) => {
+        return truthy(context[name]) ? '' : body;
+    });
+    return out;
+}
+function renderInterpolations(input, context) {
+    return input.replace(/\$\{([A-Z0-9_]+)\}/g, (_match, name) => {
+        const value = context[name];
+        if (value === null || value === undefined || value === false)
+            return '';
+        return String(value);
+    });
+}
+function truthy(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (value === false)
+        return false;
+    if (value === '' || value === 0)
+        return false;
+    return true;
+}
+//# sourceMappingURL=template.js.map

package/dist/installer/util/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/installer/util/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,QAAgB,EAAE,OAAwB;IAC/D,IAAI,GAAG,GAAG,QAAQ,CAAA;IAClB,4DAA4D;IAC5D,2CAA2C;IAC3C,GAAG,GAAG,kBAAkB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IACtC,4BAA4B;IAC5B,GAAG,GAAG,oBAAoB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IACxC,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAa,EAAE,OAAwB;IACjE,MAAM,OAAO,GAAG,8CAA8C,CAAA;IAC9D,MAAM,UAAU,GAAG,oDAAoD,CAAA;IAEvE,IAAI,GAAG,GAAG,KAAK,CAAA;IACf,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,IAAY,EAAE,EAAE;QAChE,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IAC1C,CAAC,CAAC,CAAA;IACF,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,IAAY,EAAE,EAAE;QACnE,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IAC1C,CAAC,CAAC,CAAA;IACF,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAa,EAAE,OAAwB;IACnE,OAAO,KAAK,CAAC,OAAO,CAAC,qBAAqB,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,EAAE;QACnE,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;QAC3B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,KAAK;YAAE,OAAO,EAAE,CAAA;QACvE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACvD,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,KAAK,CAAA;IACjC,IAAI,KAAK,KAAK,EAAE,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAC7C,OAAO,IAAI,CAAA;AACb,CAAC"}

package/docs/deployment.md

@@ -55,7 +55,8 @@ Clone the repository for full control and the ability to customize agents.
 git clone https://github.com/fjpulidop/specrails-core
 cd specrails-core
 npm install
-./install.sh --root-dir <your-project>
+npm run build
+node bin/specrails-core.mjs init --root-dir <your-project>
 ```
 
 ### Updating

package/docs/installation.md

@@ -59,7 +59,7 @@ The plugin bundles the logic layer — agents, skills, commands, hooks, and refe
 
 | Tool | Why | Install |
 |------|-----|---------|
-| **Node.js 18+** | Required for the installer | [nodejs.org](https://nodejs.org/) or via [nvm](https://github.com/nvm-sh/nvm) |
+| **Node.js 20+** | Required for the installer (macOS, Linux, Windows) | [nodejs.org](https://nodejs.org/) or via [nvm](https://github.com/nvm-sh/nvm) |
 | **Git** | SpecRails operates on git repositories | [git-scm.com](https://git-scm.com/) |
 | **Claude Code** or **Codex CLI** | The AI CLI that runs the agents | See [codex-vs-claude-code.md](user-docs/codex-vs-claude-code.md) |
 
@@ -75,7 +75,10 @@ No cloning required. Downloads the latest version and runs the installer automat
 
 ```bash
 git clone https://github.com/fjpulidop/specrails-core.git
-./specrails-core/install.sh --root-dir <your-project>
+cd specrails-core
+npm install
+npm run build
+node bin/specrails-core.mjs init --root-dir <your-project>
 ```
 
 > **Important:** Always run the installer from the **target repository** — the project where you want SpecRails installed.
@@ -349,7 +352,7 @@ You're running the installer from inside the SpecRails repo. Run it from your ta
 
 ```bash
 cd /path/to/your-project
-bash /path/to/specrails/install.sh
+npx specrails-core@latest init
 ```
 
 ### Existing `.claude/` directory detected

package/docs/testing/test-matrix-codex.md

@@ -100,12 +100,22 @@ Epic: [SPEA-505](/SPEA/issues/SPEA-505) — Codex Compatibility Approach B
 
 ## Test Files
 
+The shell-based test suite was retired in v4.2.0 when the installer
+moved to native Node. Coverage is now provided by vitest specs
+co-located with the installer source:
+
 | File | Suite | Covers |
 |------|-------|--------|
-| `tests/test-install.sh` | Install | Existing install flow (Claude Code only) |
-| `tests/test-update.sh` | Update | Update flow (existing) |
-| `tests/test-cli.sh` | CLI | Argument validation, injection safety |
-| `tests/test-codex-compat.sh` | Codex compat | Provider detection, dual-output structure, edge cases |
+| `src/installer/commands/init.test.ts` | Install | init flow end-to-end (Claude + Codex) |
+| `src/installer/commands/update.test.ts` | Update | update flow + reserved paths + --only |
+| `src/installer/commands/doctor.test.ts` | Doctor | health checks against fixture repos |
+| `src/installer/cli.test.ts` | CLI | Argument parsing, dispatch, exit codes |
+| `src/installer/phases/scaffold.test.ts` | Scaffold | template placement, VPC exclusion, agent-teams gate |
+| `src/installer/phases/manifest.test.ts` | Manifest | sha256 stability, sorted output, exclusions |
+| `src/installer/phases/install-config.test.ts` | Config validation | YAML round-trip + validation errors |
+| `src/installer/phases/provider-detect.test.ts` | Provider | claude vs codex resolution + Codex coming-soon error |
+| `src/installer/phases/prereqs.test.ts` | Prereqs | OSS detection + provider auth |
+| `src/installer/__tests__/reserved-paths.test.ts` | Reserved paths | profile + custom-* survival across init/update |
 
 ---
 
@@ -113,10 +123,8 @@ Epic: [SPEA-505](/SPEA/issues/SPEA-505) — Codex Compatibility Approach B
 
 Before SPEA-505 can be merged and released:
 
-1. `tests/test-codex-compat.sh` — all tests green
-2. `tests/test-install.sh` — all existing tests still green (regression)
-3. `tests/test-update.sh` — all existing tests still green (regression)
-4. `tests/test-cli.sh` — all existing tests still green (regression)
-5. No broken placeholders: `grep -r '{{[A-Z_]*}}' .claude/agents/ .codex/agents/ 2>/dev/null` returns empty
-6. Skills valid: every `SKILL.md` in `.claude/skills/` has required frontmatter
-7. Agent TOML valid: every `.toml` in `.codex/agents/` is parseable TOML
+1. `npm run test` — full vitest suite green (currently 168 specs).
+2. CI matrix `[ubuntu, macos, windows] × [node 20, 22]` all green.
+3. No broken placeholders: `grep -r '{{[A-Z_]*}}' .claude/agents/ .codex/agents/ 2>/dev/null` returns empty.
+4. Skills valid: every `SKILL.md` in `.claude/skills/` has required frontmatter.
+5. Agent TOML valid: every `.toml` in `.codex/agents/` is parseable TOML.