codz-cli 0.0.0-stage → 0.1.2

package/dist/starters/http.js

@@ -0,0 +1,93 @@
+// The only network code in codz. Every request goes to the catalog or its
+// API, announces itself once per run, has a timeout and a size cap, and maps
+// failures to codz error codes. Tokens go in the Authorization header and
+// are never part of a message.
+import { ToolError } from "../core/types.js";
+let announced = false;
+let announcer = (m) => process.stderr.write(`${m}\n`);
+export function setAnnouncer(fn) {
+    announcer = fn;
+    announced = false;
+}
+function announce(url) {
+    if (announced)
+        return;
+    announced = true;
+    announcer(`Contacting the starter catalog at ${url.host} (codz new and starters commands only; nothing about your projects is sent).`);
+}
+/** https only, except a local test server. */
+export function checkUrl(raw, what) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new ToolError('bad_registry', `${what} is not a URL: ${raw.slice(0, 100)}`);
+    }
+    const local = u.hostname === '127.0.0.1' || u.hostname === 'localhost' || u.hostname === '[::1]';
+    if (u.protocol !== 'https:' && !(u.protocol === 'http:' && local))
+        throw new ToolError('bad_registry', `${what} must use https: ${u.origin}`);
+    if (u.username || u.password)
+        throw new ToolError('bad_registry', `${what} must not contain a user name or password.`);
+    return u;
+}
+export async function request(url, opts) {
+    announce(url);
+    const headers = { 'user-agent': 'codz', accept: 'application/json, application/octet-stream' };
+    if (opts.json !== undefined)
+        headers['content-type'] = 'application/json';
+    if (opts.token)
+        headers.authorization = `Bearer ${opts.token}`;
+    if (opts.etag)
+        headers['if-none-match'] = opts.etag;
+    let res;
+    try {
+        res = await fetch(url, { method: opts.method ?? 'GET', headers, body: opts.json === undefined ? undefined : JSON.stringify(opts.json), redirect: 'error', signal: AbortSignal.timeout(opts.timeoutMs ?? 30_000) });
+    }
+    catch (e) {
+        const timeout = e.name === 'TimeoutError';
+        throw new ToolError('network_unavailable', `Could not reach the starter catalog (${url.host}): ${timeout ? 'timed out' : 'connection failed'}.`, 'Check the connection, or use a starter that is already downloaded with --cached.');
+    }
+    const len = Number(res.headers.get('content-length') ?? '0');
+    if (len > opts.maxBytes)
+        throw new ToolError('archive_too_large', `The response from ${url.host} is larger than the safety limit.`, 'Report it; nothing was written.');
+    // Read with a running cap, so a server that lies about the length cannot fill memory.
+    const chunks = [];
+    let total = 0;
+    if (res.body) {
+        const reader = res.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.length;
+            if (total > opts.maxBytes) {
+                await reader.cancel();
+                throw new ToolError('archive_too_large', `The response from ${url.host} is larger than the safety limit.`, 'Report it; nothing was written.');
+            }
+            chunks.push(Buffer.from(value));
+        }
+    }
+    return { status: res.status, body: Buffer.concat(chunks), headers: res.headers };
+}
+/** Turns a failed API answer into the matching codz error. */
+export function apiError(r, ctx) {
+    let code = '';
+    try {
+        code = String(JSON.parse(r.body.toString('utf8')).error ?? '');
+    }
+    catch {
+        // Not JSON.
+    }
+    if (r.status === 401)
+        return ctx.hadToken ? new ToolError('token_expired', 'Your session has expired.', 'Run codz login again.') : new ToolError('not_logged_in', `${ctx.what} needs an account.`, 'Run codz login.');
+    if (r.status === 403)
+        return new ToolError('no_entitlement', `This account does not own ${ctx.what}.`, 'Buy it in the gallery, then run codz whoami to refresh.');
+    if (r.status === 404)
+        return new ToolError(code === 'version_not_found' ? 'version_not_found' : 'template_not_found', `${ctx.what} was not found in the catalog.`, 'Check the id with codz starters list.');
+    if (r.status === 429) {
+        const after = r.headers.get('retry-after');
+        return new ToolError('rate_limited', 'Too many download requests.', `Wait${after ? ` ${after} seconds` : ' a while'} and try again.`);
+    }
+    return new ToolError('network_unavailable', `The starter catalog answered ${r.status} for ${ctx.what}.`, 'Try again later; report it if it persists.');
+}

package/dist/starters/manifest.js

@@ -0,0 +1,285 @@
+// The starter manifest: what a template is, what it asks, which allowlisted
+// steps it needs and the hash of every file. It is data only; nothing in it is
+// ever run. Unknown top-level fields are refused so a newer, stricter format
+// cannot be half-understood by an older codz.
+import { ToolError } from "../core/types.js";
+import { parseStrictJson } from "./strictJson.js";
+import { checkCollisions, checkRelPath, LIMITS } from "./paths.js";
+export const SCHEMA = 1;
+/** Which steps each framework may use. Nothing outside this table can ever run. */
+export const STEP_ALLOWLIST = {
+    flutter_create: { frameworks: ['flutter'], when: 'before-move', label: 'flutter create (the platform folders)' },
+    flutter_pub_get: { frameworks: ['flutter'], when: 'after-move', label: 'flutter pub get' },
+    dart_format: { frameworks: ['flutter'], when: 'after-move', label: 'dart format .' },
+    npm_install: { frameworks: ['nextjs', 'react-native'], when: 'after-move', label: 'npm install --ignore-scripts (no package install scripts run)' },
+};
+const TOP_KEYS = new Set(['schema', 'id', 'version', 'title', 'summary', 'framework', 'mode', 'requires', 'tested', 'provides', 'extras', 'apiAdd', 'answers', 'dependencies', 'devDependencies', 'steps', 'expectedConventions', 'files', 'license']);
+export const ID_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export const VERSION_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const KEY_RE = /^[a-zA-Z][a-zA-Z0-9]*$/;
+const PKG_RE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const RANGE_PART = /^(\^|~|>=|<=|>|<|=)?\d+(\.\d+){0,2}$/;
+const bad = (msg) => {
+    throw new ToolError('bad_template', `The manifest is not valid: ${msg}.`, 'Report it; the template is not usable as published.');
+};
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const str = (v, name, max = 200) => {
+    if (typeof v !== 'string' || !v || v.length > max)
+        bad(`${name} must be text of 1-${max} characters`);
+    return v;
+};
+const strMap = (v, name, keyRe, max = 100) => {
+    if (v === undefined)
+        return {};
+    if (!isObj(v))
+        bad(`${name} must be an object`);
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+        if (!keyRe.test(k))
+            bad(`${name} has a bad key "${k.slice(0, 60)}"`);
+        out[k] = str(val, `${name}.${k}`, max);
+    }
+    return out;
+};
+export function parseManifest(text) {
+    const raw = parseStrictJson(text, 'manifest.json', { maxBytes: 4 * 1024 * 1024, maxString: 4096 });
+    if (!isObj(raw))
+        return bad('it must be a JSON object');
+    const o = raw;
+    for (const k of Object.keys(o))
+        if (!TOP_KEYS.has(k))
+            bad(`unknown field "${k.slice(0, 60)}" (a newer codz may be needed)`);
+    if (o.schema !== SCHEMA)
+        throw new ToolError('template_incompatible', `This template uses manifest schema ${String(o.schema)}; this codz reads schema ${SCHEMA}.`, 'Update codz, or pick an older version of the template.');
+    const id = str(o.id, 'id', 64);
+    if (!ID_RE.test(id))
+        bad('id must be lowercase letters, digits and dashes');
+    const version = str(o.version, 'version', 32);
+    if (!VERSION_RE.test(version))
+        bad('version must be x.y.z');
+    const framework = o.framework;
+    if (!['flutter', 'nextjs', 'react-native', 'android'].includes(framework))
+        bad('framework must be flutter, nextjs, react-native or android');
+    const mode = o.mode;
+    if (mode !== 'overlay' && mode !== 'full')
+        bad('mode must be overlay or full');
+    if (mode === 'overlay' && framework !== 'flutter')
+        bad('overlay mode is only for Flutter (on flutter create)');
+    if (!isObj(o.requires))
+        bad('requires must be an object');
+    const requires = strMap(o.requires, 'requires', /^(codz|flutter|node)$/);
+    for (const [k, r] of Object.entries(requires))
+        if (!r.split(/\s+/).every((p) => RANGE_PART.test(p)))
+            bad(`requires.${k} is not a version range`);
+    let tested;
+    if (o.tested !== undefined) {
+        if (!isObj(o.tested))
+            bad('tested must be an object');
+        const t = o.tested;
+        for (const k of Object.keys(t))
+            if (!['flutter', 'node', 'date'].includes(k))
+                bad(`tested has unknown field "${k.slice(0, 40)}"`);
+        const list = (v, n) => {
+            if (v === undefined)
+                return undefined;
+            if (!Array.isArray(v) || v.length > 20)
+                bad(`tested.${n} must be a short list`);
+            return v.map((x) => str(x, `tested.${n}`, 20));
+        };
+        tested = { flutter: list(t.flutter, 'flutter'), node: list(t.node, 'node'), date: t.date === undefined ? undefined : str(t.date, 'tested.date', 10) };
+    }
+    if (!isObj(o.apiAdd) || typeof o.apiAdd.supported !== 'boolean')
+        bad('apiAdd.supported must be true or false');
+    const apiAddRaw = o.apiAdd;
+    const apiAdd = { supported: apiAddRaw.supported, note: apiAddRaw.note === undefined ? undefined : str(apiAddRaw.note, 'apiAdd.note', 300) };
+    if (!Array.isArray(o.answers) || o.answers.length > 20)
+        bad('answers must be a list of at most 20 questions');
+    const answers = o.answers.map((a, n) => {
+        if (!isObj(a))
+            return bad(`answers[${n}] must be an object`);
+        const r = a;
+        for (const k of Object.keys(r))
+            if (!['key', 'prompt', 'type', 'default', 'choices', 'maxLength'].includes(k))
+                bad(`answers[${n}] has unknown field "${k.slice(0, 40)}"`);
+        const key = str(r.key, `answers[${n}].key`, 40);
+        if (!KEY_RE.test(key))
+            bad(`answers[${n}].key must be letters and digits`);
+        const type = r.type;
+        if (!['identifier', 'npm-name', 'reverse-domain', 'string', 'choice', 'boolean'].includes(type))
+            bad(`answers[${n}].type is not a known answer type`);
+        const choices = r.choices === undefined ? undefined : Array.isArray(r.choices) && r.choices.length && r.choices.length <= 30 ? r.choices.map((c) => str(c, `answers[${n}].choices`, 60)) : bad(`answers[${n}].choices must be a short list`);
+        if (type === 'choice' && !choices)
+            bad(`answers[${n}] is a choice without choices`);
+        const def = r.default;
+        if (def !== undefined && typeof def !== 'string' && typeof def !== 'boolean')
+            bad(`answers[${n}].default must be text or true/false`);
+        const maxLength = r.maxLength === undefined ? undefined : typeof r.maxLength === 'number' && r.maxLength > 0 && r.maxLength <= 500 ? r.maxLength : bad(`answers[${n}].maxLength must be 1-500`);
+        return { key, prompt: str(r.prompt, `answers[${n}].prompt`, 120), type, default: def, choices, maxLength };
+    });
+    if (new Set(answers.map((a) => a.key)).size !== answers.length)
+        bad('two answers use the same key');
+    const appName = answers.find((a) => a.key === 'appName');
+    if (!appName)
+        bad('it needs an appName answer');
+    if (framework === 'flutter' && appName.type !== 'identifier')
+        bad('a Flutter appName must be an identifier answer');
+    if (mode === 'overlay' && answers.find((a) => a.key === 'org')?.type !== 'reverse-domain')
+        bad('overlay mode needs an org answer of type reverse-domain (for flutter create --org)');
+    if (!Array.isArray(o.steps))
+        bad('steps must be a list');
+    const steps = o.steps.map((s) => {
+        if (typeof s !== 'string' || !(s in STEP_ALLOWLIST))
+            bad(`step "${String(s).slice(0, 40)}" is not on codz's allowlist (${Object.keys(STEP_ALLOWLIST).join(', ')})`);
+        if (!STEP_ALLOWLIST[s].frameworks.includes(framework))
+            bad(`step ${s} is not allowed for ${framework}`);
+        return s;
+    });
+    if (new Set(steps).size !== steps.length)
+        bad('a step is listed twice');
+    if (mode === 'overlay' && !steps.includes('flutter_create'))
+        bad('overlay mode needs the flutter_create step');
+    if (!Array.isArray(o.files) || !o.files.length || o.files.length > LIMITS.entries)
+        bad(`files must list 1-${LIMITS.entries} files`);
+    const files = o.files.map((f, n) => {
+        if (!isObj(f))
+            return bad(`files[${n}] must be an object`);
+        const r = f;
+        for (const k of Object.keys(r))
+            if (!['path', 'sha256', 'size', 'mode'].includes(k))
+                bad(`files[${n}] has unknown field "${k.slice(0, 40)}"`);
+        const path = checkRelPath(str(r.path, `files[${n}].path`, LIMITS.pathLength), 'manifest');
+        const sha256 = str(r.sha256, `files[${n}].sha256`, 64);
+        if (!/^[0-9a-f]{64}$/.test(sha256))
+            bad(`files[${n}].sha256 must be 64 lowercase hex characters`);
+        if (typeof r.size !== 'number' || !Number.isInteger(r.size) || r.size < 0 || r.size > LIMITS.fileBytes)
+            bad(`files[${n}].size is not a valid size`);
+        if (r.mode !== undefined && r.mode !== '644' && r.mode !== '755')
+            bad(`files[${n}].mode must be "644" or "755"`);
+        return { path, sha256, size: r.size, mode: r.mode };
+    });
+    checkCollisions(files.map((f) => f.path), 'manifest');
+    if (files.reduce((n, f) => n + f.size, 0) > LIMITS.expandedBytes)
+        throw new ToolError('archive_too_large', 'The template is larger than the safety limit.', 'Report it; nothing was written.');
+    if (!isObj(o.license))
+        bad('license must be an object');
+    const lic = o.license;
+    if (lic.file !== 'LICENSE')
+        bad('license.file must be "LICENSE"');
+    const license = { kind: str(lic.kind, 'license.kind', 60), file: 'LICENSE' };
+    const extras = o.extras === undefined ? undefined : Array.isArray(o.extras) && o.extras.length <= 30 ? o.extras.map((e) => str(e, 'extras', 200)) : bad('extras must be a short list');
+    return {
+        schema: SCHEMA,
+        id,
+        version,
+        title: str(o.title, 'title', 120),
+        summary: o.summary === undefined ? undefined : str(o.summary, 'summary', 500),
+        framework,
+        mode,
+        requires,
+        tested,
+        provides: strMap(o.provides, 'provides', /^[a-zA-Z]+$/, 60),
+        extras,
+        apiAdd,
+        answers,
+        dependencies: strMap(o.dependencies, 'dependencies', PKG_RE, 100),
+        devDependencies: strMap(o.devDependencies, 'devDependencies', PKG_RE, 100),
+        steps,
+        expectedConventions: strMap(o.expectedConventions, 'expectedConventions', /^[a-zA-Z]+$/, 200),
+        files,
+        license,
+    };
+}
+// ---------- Versions ----------
+const parts = (v) => v.split('.').map((x) => Number(x));
+export function compareVersions(a, b) {
+    const x = parts(a);
+    const y = parts(b);
+    for (let i = 0; i < 3; i++) {
+        const d = (x[i] ?? 0) - (y[i] ?? 0);
+        if (d)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** ">=3.24 <4.0", "^1.2.0", "~2.1", "=1.0.0": every part must hold. */
+export function satisfies(version, range) {
+    const v = version.replace(/^v/, '').split(/[-+]/)[0];
+    return range.trim().split(/\s+/).every((p) => {
+        const m = /^(\^|~|>=|<=|>|<|=)?(\d+(?:\.\d+){0,2})$/.exec(p);
+        if (!m)
+            return false;
+        const [, op = '=', target] = m;
+        const c = compareVersions(v, target);
+        const t = parts(target);
+        switch (op) {
+            case '>=':
+                return c >= 0;
+            case '<=':
+                return c <= 0;
+            case '>':
+                return c > 0;
+            case '<':
+                return c < 0;
+            case '^':
+                return c >= 0 && (t[0] > 0 ? parts(v)[0] === t[0] : parts(v)[1] === (t[1] ?? 0));
+            case '~':
+                return c >= 0 && parts(v)[0] === t[0] && parts(v)[1] === (t[1] ?? 0);
+            default:
+                return c === 0 || (t.length < 3 && parts(v).slice(0, t.length).join('.') === t.join('.'));
+        }
+    });
+}
+export function checkAnswer(spec, value) {
+    if (spec.type === 'boolean')
+        return typeof value === 'boolean' ? null : 'Use true or false.';
+    if (typeof value !== 'string')
+        return 'Use text.';
+    const max = spec.maxLength ?? (spec.type === 'string' ? 100 : 64);
+    if (value.length > max)
+        return `Use at most ${max} characters.`;
+    switch (spec.type) {
+        case 'identifier':
+            return /^[a-z][a-z0-9_]*$/.test(value) ? null : 'Use lowercase letters, digits and _, starting with a letter (for example shop_app).';
+        case 'npm-name':
+            return /^[a-z][a-z0-9-_]*$/.test(value) ? null : 'Use lowercase letters, digits, - and _, starting with a letter (for example shop-app).';
+        case 'reverse-domain':
+            return /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(value) ? null : 'Use reverse-domain form, for example com.acme.';
+        case 'choice':
+            return spec.choices.includes(value) ? null : `Choose one of: ${spec.choices.join(', ')}.`;
+        case 'string':
+            // Printable text only: no control characters, no placeholder braces, no backticks or $ (they mean something in code).
+            // eslint-disable-next-line no-control-regex
+            return value && !/[\u0000-\u001f\u007f{}`$\\"'<>]/.test(value) ? null : 'Use plain printable text without quotes, braces, angle brackets, backticks, $ or backslashes.';
+    }
+    return 'Unknown answer type.';
+}
+/** Fills in defaults and validates every answer. `given` comes from --set and the name argument. */
+export function resolveAnswers(m, given) {
+    for (const k of Object.keys(given))
+        if (!m.answers.some((a) => a.key === k))
+            throw new ToolError('bad_answer', `This template has no question "${k}".`, `Its questions: ${m.answers.map((a) => a.key).join(', ')}`);
+    const out = {};
+    for (const a of m.answers) {
+        let v = given[a.key] ?? a.default;
+        if (a.type === 'boolean' && typeof v === 'string')
+            v = v === 'true' ? true : v === 'false' ? false : v;
+        if (v === undefined)
+            throw new ToolError('bad_answer', `No value for "${a.key}" (${a.prompt}).`, `Pass --set ${a.key}=<value>.`);
+        const problem = checkAnswer(a, v);
+        if (problem)
+            throw new ToolError('bad_answer', `The value for ${a.key} is not valid. ${problem}`, `Pass --set ${a.key}=<value>.`);
+        out[a.key] = v;
+    }
+    return out;
+}
+/** Placeholder values: every answer as {{key}}, and each reverse-domain answer as a path too ({{org.path}} = com/acme). */
+export function placeholderValues(m, answers) {
+    const vals = new Map();
+    for (const a of m.answers) {
+        const v = answers[a.key];
+        vals.set(a.key, String(v));
+        if (a.type === 'reverse-domain')
+            vals.set(`${a.key}.path`, String(v).replace(/\./g, '/'));
+    }
+    return vals;
+}

package/dist/starters/paths.js

@@ -0,0 +1,70 @@
+// Path rules for every file a starter writes. A path is checked when it is
+// read from an archive or folder, and again after placeholders are filled in,
+// because an answer can change a path.
+import { ToolError } from "../core/types.js";
+export const LIMITS = {
+    compressedBytes: 50 * 1024 * 1024,
+    expandedBytes: 200 * 1024 * 1024,
+    entries: 5000,
+    pathLength: 240,
+    depth: 32,
+    fileBytes: 50 * 1024 * 1024,
+};
+const RESERVED = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\..*)?$/i;
+/** Throws archive_unsafe unless `p` is a safe relative path with forward slashes. */
+export function checkRelPath(p, where) {
+    const unsafe = (why) => {
+        throw new ToolError('archive_unsafe', `The ${where} has an unsafe entry "${clip(p)}": ${why}. Nothing was written.`, 'Do not use this template; report it.');
+    };
+    if (!p)
+        unsafe('an empty name');
+    if (p.length > LIMITS.pathLength)
+        unsafe(`a path longer than ${LIMITS.pathLength} characters`);
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f\\:*?"<>|]/.test(p))
+        unsafe('a character that is not allowed in file names');
+    if (p.startsWith('/') || /^[a-zA-Z]:/.test(p))
+        unsafe('an absolute path');
+    const segs = p.split('/');
+    if (segs.length > LIMITS.depth)
+        unsafe(`more than ${LIMITS.depth} nested folders`);
+    for (const s of segs) {
+        if (s === '' || s === '.')
+            unsafe('an empty or "." path segment');
+        if (s === '..')
+            unsafe('a ".." segment');
+        if (RESERVED.test(s))
+            unsafe(`a name reserved on Windows (${s})`);
+        if (/[. ]$/.test(s))
+            unsafe('a name ending in a dot or a space');
+        if (s === '.git')
+            unsafe('a .git folder');
+        if (s === '.codz')
+            unsafe("codz's own folder");
+    }
+    return p;
+}
+/** Case- and Unicode-folded form: two paths with the same key collide on macOS and Windows. */
+export function collisionKey(p) {
+    return p.normalize('NFC').toLowerCase();
+}
+/** Throws archive_unsafe when two file paths would land on the same file on some system, or a file is also used as a folder. */
+export function checkCollisions(paths, where) {
+    const files = new Map();
+    for (const p of paths) {
+        const k = collisionKey(p);
+        const prev = files.get(k);
+        if (prev !== undefined)
+            throw new ToolError('archive_unsafe', `The ${where} has two entries that are the same file on macOS and Windows: "${clip(prev)}" and "${clip(p)}". Nothing was written.`, 'Do not use this template; report it.');
+        files.set(k, p);
+    }
+    for (const p of paths) {
+        const segs = p.split('/');
+        for (let n = 1; n < segs.length; n++) {
+            const dir = segs.slice(0, n).join('/');
+            if (files.has(collisionKey(dir)))
+                throw new ToolError('archive_unsafe', `The ${where} uses "${clip(dir)}" as both a file and a folder. Nothing was written.`, 'Do not use this template; report it.');
+        }
+    }
+}
+const clip = (s) => (s.length > 120 ? `${s.slice(0, 117)}...` : s).replace(/[\u0000-\u001f]/g, '?');

package/dist/starters/publish.js

@@ -0,0 +1,150 @@
+// Publishing starters (internal): check a template folder against the
+// publishing gates, refresh its file list, pack it into a deterministic
+// archive, and build and sign the catalog index. Used by scripts/starters.ts
+// and by the tests' fake registry. Nothing here runs on a user's `codz new`.
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ToolError } from "../core/types.js";
+import { planNew } from "./engine.js";
+import { resolveAnswers } from "./manifest.js";
+import { sha256, signatureFile } from "./sign.js";
+import { fromFolder } from "./source.js";
+import { parseStrictJson } from "./strictJson.js";
+import { writeTarGz } from "./tar.js";
+/** Rewrites manifest.json's file list (paths, hashes, sizes, executable bits) from files/. */
+export function refreshFileList(dir) {
+    const files = [];
+    const walk = (rel) => {
+        for (const name of readdirSync(join(dir, 'files', rel)).sort()) {
+            const p = rel ? `${rel}/${name}` : name;
+            const st = lstatSync(join(dir, 'files', p));
+            if (st.isDirectory())
+                walk(p);
+            else if (st.isFile()) {
+                const data = readFileSync(join(dir, 'files', p));
+                files.push({ path: p, sha256: sha256(data), size: data.length, ...(st.mode & 0o111 ? { mode: '755' } : {}) });
+            }
+            else
+                throw new ToolError('archive_unsafe', `files/${p} is a link or special file; templates hold regular files only.`);
+        }
+    };
+    walk('');
+    const m = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8'));
+    m.files = files;
+    writeFileSync(join(dir, 'manifest.json'), JSON.stringify(m, null, 2) + '\n');
+    return files.length;
+}
+const SECRET_PATTERNS = [
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, 'a private key'],
+    [/\bAKIA[0-9A-Z]{16}\b/, 'an AWS access key'],
+    [/\bgh[pousr]_[A-Za-z0-9]{36,}\b/, 'a GitHub token'],
+    [/\bsk_(live|test)_[A-Za-z0-9]{16,}\b/, 'a Stripe key'],
+    [/\bAIza[0-9A-Za-z_-]{35}\b/, 'a Google API key'],
+];
+/** The static and determinism gates: everything that can be checked without an SDK. */
+export function checkTemplate(dir, codzVersion) {
+    const errors = [];
+    const warnings = [];
+    const t = fromFolder(dir); // manifest schema, paths, hashes, links
+    const m = t.manifest;
+    const keys = new Set(m.answers.flatMap((a) => (a.type === 'reverse-domain' ? [a.key, `${a.key}.path`] : [a.key])));
+    for (const [path, data] of t.files) {
+        for (const k of [...path.matchAll(/\{\{([^}]+)\}\}/g)].map((x) => x[1]))
+            if (!keys.has(k))
+                errors.push(`${path}: the path uses {{${k}}}, which no answer fills in`);
+        const text = data.includes(0) ? '' : data.toString('utf8');
+        for (const [re, what] of SECRET_PATTERNS)
+            if (re.test(text))
+                errors.push(`${path}: looks like it contains ${what}`);
+        for (const k of new Set([...text.matchAll(/\{\{([a-zA-Z][a-zA-Z0-9]*(?:\.path)?)\}\}/g)].map((x) => x[1])))
+            if (!keys.has(k))
+                warnings.push(`${path}: {{${k}}} is not an answer, so it is left as written`);
+    }
+    if (!t.license.trim())
+        errors.push('LICENSE is empty');
+    if (!m.extras?.length)
+        warnings.push('No "extras": the catalog page will not say what this starter adds beyond codz create');
+    if (!m.tested)
+        warnings.push('No "tested" block: fill it from the CI matrix results');
+    if (!Object.keys(m.expectedConventions ?? {}).length)
+        errors.push('No expectedConventions: the init contract test has nothing to check');
+    // Determinism: the same answers give the same files.
+    const answers = resolveAnswers(m, {});
+    const plan = () => planNew(t, answers, '/tmp/codz-check', codzVersion, null, { steps: true });
+    const a = plan();
+    const b = plan();
+    const digest = (p) => sha256(Buffer.concat(p.files.flatMap((f) => [Buffer.from(`${f.path}\0${f.mode}\0`), f.data])));
+    if (digest(a) !== digest(b))
+        errors.push('Two builds with the same answers differ');
+    return { id: m.id, version: m.version, errors, warnings };
+}
+/** Packs a checked template folder: <out>/v1/templates/<id>/<version>/{archive.tar.gz, manifest.json}. */
+export function packTemplate(dir, out) {
+    const t = fromFolder(dir);
+    const m = t.manifest;
+    const entries = new Map([
+        ['manifest.json', t.manifestBytes],
+        ['LICENSE', Buffer.from(t.license)],
+    ]);
+    const exec = new Set();
+    for (const f of m.files) {
+        entries.set(`files/${f.path}`, t.files.get(f.path));
+        if (f.mode === '755')
+            exec.add(`files/${f.path}`);
+    }
+    const gz = writeTarGz(entries, exec);
+    const dest = join(out, 'v1', 'templates', m.id, m.version);
+    mkdirSync(dest, { recursive: true });
+    const archive = join(dest, 'archive.tar.gz');
+    if (existsSync(archive) && sha256(readFileSync(archive)) !== sha256(gz))
+        throw new ToolError('version_exists', `${m.id} ${m.version} is already published with different contents.`, 'A published version never changes: raise the version number.');
+    writeFileSync(archive, gz);
+    writeFileSync(join(dest, 'manifest.json'), t.manifestBytes);
+    return { id: m.id, version: m.version, archiveSha256: sha256(gz), manifestSha256: sha256(t.manifestBytes), archive };
+}
+/** Builds v1/index.json from the packed versions and catalog.json, with seq + 1, and signs it. */
+export function buildIndex(root, privatePems, opts = {}) {
+    const catalog = parseStrictJson(readFileSync(join(root, 'catalog.json'), 'utf8'), 'catalog.json');
+    const prevPath = join(root, 'v1', 'index.json');
+    const prevSeq = existsSync(prevPath) ? JSON.parse(readFileSync(prevPath, 'utf8')).seq : 0;
+    const now = opts.now ?? new Date();
+    const templates = [];
+    for (const c of catalog.templates) {
+        const base = join(root, 'v1', 'templates', c.id);
+        if (!existsSync(base))
+            throw new ToolError('template_not_found', `catalog.json lists ${c.id}, but nothing is packed for it.`);
+        const versions = readdirSync(base).filter((v) => statSync(join(base, v)).isDirectory()).sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+        let latestManifest = null;
+        const vs = versions.map((v) => {
+            const archive = readFileSync(join(base, v, 'archive.tar.gz'));
+            const manifestBytes = readFileSync(join(base, v, 'manifest.json'));
+            const m = JSON.parse(manifestBytes.toString('utf8'));
+            if (!c.yanked?.includes(v))
+                latestManifest = m;
+            return { version: v, archive: { sha256: sha256(archive), size: archive.length }, manifest: { sha256: sha256(manifestBytes) }, tested: m.tested, ...(c.yanked?.includes(v) ? { yanked: true } : {}), ...(c.needsUpdate?.includes(v) ? { needsUpdate: true } : {}) };
+        });
+        const lm = (latestManifest ?? JSON.parse(readFileSync(join(base, versions[versions.length - 1], 'manifest.json'), 'utf8')));
+        templates.push({ id: c.id, title: c.title ?? lm.title, summary: c.summary ?? lm.summary, framework: lm.framework, tier: c.tier, price: c.price, provides: lm.provides, apiAdd: lm.apiAdd.supported, extras: lm.extras, latest: lm.version, versions: vs });
+    }
+    const index = { schema: 1, seq: prevSeq + 1, issued: now.toISOString(), expires: new Date(now.getTime() + (opts.days ?? 7) * 86_400_000).toISOString(), templates, revoked: catalog.revoked ?? [], ...(opts.timestampKeys?.length ? { timestampKeys: opts.timestampKeys } : {}) };
+    const bytes = Buffer.from(JSON.stringify(index, null, 2) + '\n');
+    mkdirSync(join(root, 'v1'), { recursive: true });
+    writeFileSync(prevPath, bytes);
+    writeFileSync(`${prevPath}.sig`, signatureFile(bytes, privatePems));
+    return index;
+}
+/**
+ * Signs v1/timestamp.json for the current v1/index.json with an online key: "this index
+ * is current until <expires>". The store does this every few hours; this is the same
+ * thing for a cron job or a static host.
+ */
+export function signTimestamp(root, privatePem, opts = {}) {
+    const bytes = readFileSync(join(root, 'v1', 'index.json'));
+    const index = JSON.parse(bytes.toString('utf8'));
+    const now = opts.now ?? new Date();
+    const ts = { schema: 1, index_sha256: sha256(bytes), seq: index.seq, issued: now.toISOString(), expires: new Date(now.getTime() + (opts.hours ?? 48) * 3_600_000).toISOString() };
+    const out = Buffer.from(JSON.stringify(ts, null, 2) + '\n');
+    writeFileSync(join(root, 'v1', 'timestamp.json'), out);
+    writeFileSync(join(root, 'v1', 'timestamp.json.sig'), signatureFile(out, [privatePem]));
+    return { seq: index.seq, expires: ts.expires };
+}