codz-cli 0.0.0-stage → 0.1.2

package/dist/starters/commands.js

@@ -0,0 +1,283 @@
+// codz new, starters list|show|cache, login, logout, whoami, and applying
+// a saved `new` plan. The main CLI loads this file only when one of these
+// commands runs, so the rest of codz never loads network code.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { newId } from "../core/changeset.js";
+import { hash } from "../core/fsutil.js";
+import { ToolError } from "../core/types.js";
+import { auth } from "./auth.js";
+import { applyNew, detectSdks, planNew, renderPlan, undoNew } from "./engine.js";
+import { homePath, readHomeFile, removeHome, writeHomeFile } from "./home.js";
+import { setAnnouncer } from "./http.js";
+import { checkAnswer, resolveAnswers } from "./manifest.js";
+import { fetchManifest, fetchTemplate, latestUsable, loadIndex, resolveRef } from "./registry.js";
+import { fromFolder } from "./source.js";
+import { printable } from "./strictJson.js";
+const str = (flags, k) => (typeof flags[k] === 'string' ? flags[k] : '');
+function isFolderRef(ref, cwd) {
+    return /^(\.{1,2}[\\/]|[\\/]|~[\\/]|[a-zA-Z]:[\\/])/.test(ref) || /[\\/]/.test(ref) || (existsSync(resolve(cwd, ref)) && statSync(resolve(cwd, ref)).isDirectory());
+}
+async function loadTemplate(ref, ctx, cached) {
+    if (isFolderRef(ref, ctx.cwd)) {
+        const dir = resolve(ctx.cwd, ref.replace(/^~(?=[\\/])/, process.env.HOME ?? '~'));
+        return { template: fromFolder(dir), ref: dir, kind: 'folder', warnings: [] };
+    }
+    const { index, warnings } = await loadIndex({ cached });
+    const r = resolveRef(index, ref);
+    const template = await fetchTemplate(index, r.template, r.version, { cached });
+    return { template, ref: `${r.template.id}@${r.version.version}`, kind: 'catalog', warnings: [...warnings, ...r.warnings] };
+}
+async function pickFromCatalog(ctx) {
+    const { index, warnings } = await loadIndex({ cached: ctx.flags.cached === true });
+    for (const w of warnings)
+        ctx.io.warn(w);
+    const f = (k) => str(ctx.flags, k);
+    const list = index.templates.filter((t) => (!f('framework') || t.framework === f('framework')) && ['state', 'router', 'http'].every((k) => !f(k) || t.provides?.[k] === f(k)));
+    if (!list.length)
+        throw new ToolError('template_not_found', 'No starter matches those choices.', 'See them all with: codz starters list');
+    if (!ctx.io.choose)
+        throw new ToolError('bad_args', 'Which starter? Pass --template <id> (or a folder).', `Starters: ${list.map((t) => t.id).join(', ')}`);
+    const i = await ctx.io.choose('Which starter?', list.map((t) => `${t.id}  ${printable(t.title)}${t.tier === 'paid' ? `  (paid${t.price ? `, ${printable(t.price)}` : ''})` : '  (free)'}`), 0);
+    if (i === null)
+        throw new ToolError('cancelled', 'No starter chosen.');
+    const t = list[i];
+    ctx.io.print(`Same choice in a script: codz new <name> --template ${t.id}@${latestUsable(t, index)}`);
+    return `${t.id}@${latestUsable(t, index)}`;
+}
+async function collectAnswers(m, ctx) {
+    const given = {};
+    for (const s of ctx.multi.set ?? []) {
+        const eq = s.indexOf('=');
+        if (eq <= 0)
+            throw new ToolError('bad_args', `--set needs key=value, not "${s.slice(0, 60)}".`);
+        given[s.slice(0, eq)] = s.slice(eq + 1);
+    }
+    if (ctx.positional[1])
+        given.appName = ctx.positional[1];
+    if (str(ctx.flags, 'org') && m.answers.some((a) => a.key === 'org'))
+        given.org = str(ctx.flags, 'org');
+    if (ctx.io.ask) {
+        for (const a of m.answers) {
+            if (a.key in given)
+                continue;
+            if (a.type === 'boolean' && ctx.io.confirm) {
+                const v = await ctx.io.confirm(printable(a.prompt));
+                if (v !== null)
+                    given[a.key] = String(v);
+                continue;
+            }
+            if (a.type === 'choice' && ctx.io.choose) {
+                const def = Math.max(0, a.choices.indexOf(String(a.default ?? '')));
+                const i = await ctx.io.choose(printable(a.prompt), a.choices.map(printable), def);
+                if (i !== null)
+                    given[a.key] = a.choices[i];
+                continue;
+            }
+            const v = await ctx.io.ask(`${printable(a.prompt)}${a.default !== undefined ? ` [${printable(String(a.default))}]` : ''}: `, (x) => (!x && a.default !== undefined ? null : checkAnswer(a, x)));
+            if (v === null)
+                throw new ToolError('cancelled', 'Not created.');
+            if (v)
+                given[a.key] = v;
+        }
+    }
+    return given;
+}
+function planDigest(p) {
+    return hash(JSON.stringify([p.target, p.template.manifestSha256, p.template.archiveSha256 ?? '', p.files.map((f) => [f.path, f.mode, hash(f.data.toString('base64'))]), p.steps.map((s) => s.command), p.dependencies, p.devDependencies]));
+}
+function planJson(p) {
+    return {
+        template: { id: p.template.id, version: p.template.version, title: p.template.title, sha256: p.template.archiveSha256 ?? null, license: p.template.license },
+        target: p.target,
+        files: p.files.map((f) => ({ path: f.path, action: 'create', mode: f.mode })),
+        steps: p.steps.map((s) => s.id),
+        dependencies: p.dependencies,
+        apiAdd: p.apiAdd,
+        warnings: p.warnings,
+    };
+}
+async function runNew(ctx) {
+    const { flags, io } = ctx;
+    const cached = flags.cached === true;
+    const ref = str(flags, 'template') || (await pickFromCatalog(ctx));
+    const loaded = await loadTemplate(ref, ctx, cached);
+    for (const w of loaded.warnings)
+        io.warn(w);
+    const m = loaded.template.manifest;
+    const answers = resolveAnswers(m, await collectAnswers(m, ctx));
+    const parent = resolve(ctx.cwd, str(flags, 'dir') || '.');
+    const sdks = detectSdks(m.framework === 'flutter');
+    const plan = planNew(loaded.template, answers, parent, ctx.version, sdks, { steps: flags['no-steps'] !== true });
+    if (existsSync(plan.target) && readdirSync(plan.target).length)
+        throw new ToolError('dir_not_empty', `${plan.target} already exists and is not empty.`, 'Pick another name, or an empty folder.');
+    io.print(renderPlan(plan));
+    for (const w of plan.warnings)
+        io.warn(w);
+    if (flags['dry-run'] === true) {
+        io.result({ dryRun: true, ...planJson(plan) });
+        return 0;
+    }
+    const yes = flags.yes === true || flags.y === true;
+    if (flags.plan === true || (io.json && !yes)) {
+        const id = newId();
+        const saved = { id, ref: loaded.ref, kind: loaded.kind, parent, answers: Object.fromEntries(Object.entries(answers).map(([k, v]) => [k, String(v)])), steps: flags['no-steps'] !== true, digest: planDigest(plan), archiveSha256: plan.template.archiveSha256 };
+        writeHomeFile(JSON.stringify(saved, null, 2), {}, 'starters', 'plans', `${id}.json`);
+        io.print(`\nSaved plan ${id}. Create exactly this with: codz apply ${id}`);
+        io.result({ planId: id, ...planJson(plan) });
+        return 0;
+    }
+    if (!yes) {
+        if (!io.confirm)
+            throw new ToolError('needs_confirmation', 'Not created: pass --yes to create it without a question, or --plan to save it.');
+        if (!(await io.confirm('\nCreate it?'))) {
+            io.print('Not created.');
+            return 0;
+        }
+    }
+    return finishNew(plan, loaded, io);
+}
+function finishNew(plan, loaded, io) {
+    const r = applyNew(plan, (l) => io.print(l));
+    for (const w of r.warnings)
+        io.warn(w);
+    const runs = readHomeFile('starters', 'runs.json');
+    let list = [];
+    try {
+        list = runs ? JSON.parse(runs.toString('utf8')) : [];
+    }
+    catch {
+        list = [];
+    }
+    list.push({ id: r.id, template: plan.template.id, version: plan.template.version, archiveSha256: plan.template.archiveSha256 ?? null, source: loaded.kind, target: r.target, at: new Date().toISOString() });
+    writeHomeFile(JSON.stringify(list.slice(-200), null, 2), {}, 'starters', 'runs.json');
+    const name = plan.target.split(/[\\/]/).pop();
+    io.print(`\nCreated ${r.target} (${r.files} files).`);
+    if (!plan.apiAdd.supported)
+        io.warn(`codz init and explain work on this project, but api add does not support it${plan.apiAdd.note ? ` (${plan.apiAdd.note})` : ''}.`);
+    io.print(`Next: cd ${name} && codz init`);
+    io.print('Undo (inside the project, before you change it): codz undo');
+    io.result({ id: r.id, target: r.target, files: r.files, steps: r.steps, warnings: r.warnings, template: { id: plan.template.id, version: plan.template.version, sha256: plan.template.archiveSha256 ?? null } });
+    return 0;
+}
+/** codz apply <id> for a plan saved by codz new --plan. Returns null when the id is not a starter plan. */
+export async function applyStarterPlan(id, ctx) {
+    const b = readHomeFile('starters', 'plans', `${id}.json`);
+    if (!b)
+        return null;
+    const saved = JSON.parse(b.toString('utf8'));
+    const loaded = saved.kind === 'folder' ? { template: fromFolder(saved.ref), ref: saved.ref, kind: 'folder', warnings: [] } : await loadTemplate(saved.ref, ctx, ctx.flags.cached === true);
+    const answers = resolveAnswers(loaded.template.manifest, saved.answers);
+    const plan = planNew(loaded.template, answers, saved.parent, ctx.version, detectSdks(loaded.template.manifest.framework === 'flutter'), { steps: saved.steps });
+    if (planDigest(plan) !== saved.digest || (existsSync(plan.target) && readdirSync(plan.target).length))
+        throw new ToolError('changed_since_plan', 'The template or the target folder changed after the preview, so nothing was created.', 'Run codz new again for a fresh preview.');
+    const code = finishNew(plan, loaded, ctx.io);
+    removeHome('starters', 'plans', `${id}.json`);
+    return code;
+}
+export function isStarterPlan(id) {
+    return readHomeFile('starters', 'plans', `${id}.json`) !== null;
+}
+// ---------- starters list | show | cache ----------
+function line(t, latest, owned) {
+    const tier = t.tier === 'paid' ? (owned.has(t.id) ? 'owned' : `paid${t.price ? ` ${printable(t.price)}` : ''}`) : 'free';
+    return `${t.id.padEnd(36)} ${latest.padEnd(9)} ${t.framework.padEnd(13)} ${tier.padEnd(12)} ${t.apiAdd ? 'api add ✓' : 'api add ✗'}  ${printable(t.title)}`;
+}
+async function runStarters(ctx) {
+    const { sub, flags, io } = ctx;
+    if (sub === 'cache') {
+        const dir = homePath('starters', 'cache');
+        const entries = [];
+        if (existsSync(dir))
+            for (const id of readdirSync(dir))
+                for (const v of readdirSync(resolve(dir, id)))
+                    entries.push({ id, version: v });
+        if (flags.clear === true) {
+            removeHome('starters', 'cache');
+            io.print(entries.length ? `Removed ${entries.length} downloaded starter${entries.length === 1 ? '' : 's'}.` : 'The cache was already empty.');
+            io.result({ cleared: entries });
+            return 0;
+        }
+        io.print(entries.length ? entries.map((e) => `${e.id} ${e.version}`).join('\n') : 'No starters downloaded yet.');
+        io.print(`\nCache: ${dir}`);
+        io.result({ cache: dir, entries });
+        return 0;
+    }
+    const { index, warnings, fromCache } = await loadIndex({ refresh: flags.refresh === true, cached: flags.cached === true });
+    for (const w of warnings)
+        io.warn(w);
+    if (sub === 'show') {
+        const ref = ctx.positional[2];
+        if (!ref)
+            throw new ToolError('bad_args', 'Which starter? Usage: codz starters show <id>[@version]');
+        const r = resolveRef(index, ref);
+        for (const w of r.warnings)
+            io.warn(w);
+        const m = fromCache ? null : await fetchManifest(r.template, r.version);
+        const t = r.template;
+        io.print(`${t.id} ${r.version.version}  ${printable(t.title)}`);
+        if (t.summary)
+            io.print(printable(t.summary));
+        io.print(`Framework: ${t.framework}   Price: ${t.tier === 'paid' ? `paid${t.price ? ` (${printable(t.price)})` : ''}` : 'free'}   api add: ${t.apiAdd ? 'supported' : 'not supported'}`);
+        if (t.provides)
+            io.print(`Provides: ${Object.entries(t.provides).map(([k, v]) => `${k} ${printable(v)}`).join(', ')}`);
+        if (t.extras?.length)
+            io.print(`Beyond codz create:\n${t.extras.map((e) => `  - ${printable(e)}`).join('\n')}`);
+        if (m) {
+            io.print(`Needs: ${Object.entries(m.requires).map(([k, v]) => `${k} ${v}`).join(', ') || 'nothing special'}`);
+            if (m.tested)
+                io.print(`Tested with: ${[m.tested.flutter?.length ? `Flutter ${m.tested.flutter.join(', ')}` : '', m.tested.node?.length ? `Node ${m.tested.node.join(', ')}` : ''].filter(Boolean).join('; ')}${m.tested.date ? ` on ${m.tested.date}` : ''}`);
+            io.print(`License: ${printable(m.license.kind)}   Files: ${m.files.length}   Questions: ${m.answers.map((a) => a.key).join(', ')}`);
+        }
+        io.print(`Versions: ${t.versions.map((v) => `${v.version}${v.yanked ? ' (replaced)' : ''}${index.revoked.some((x) => x.id === t.id && x.version === v.version) ? ' (withdrawn)' : ''}`).join(', ')}`);
+        io.print(`\nCreate a project: codz new <name> --template ${t.id}@${r.version.version}`);
+        io.result({ template: t, version: r.version, manifest: m });
+        return 0;
+    }
+    if (sub && sub !== 'list')
+        throw new ToolError('bad_args', `Unknown command "starters ${sub}".`, 'Use: codz starters list | show <id> | cache');
+    let owned = new Set();
+    if (flags.owned === true)
+        owned = new Set((await auth.whoami()).owned.map((o) => o.id));
+    const f = (k) => str(flags, k);
+    const list = index.templates.filter((t) => (!f('framework') || t.framework === f('framework')) && ['state', 'router', 'http'].every((k) => !f(k) || t.provides?.[k] === f(k)) && (flags.free !== true || t.tier === 'free') && (flags.owned !== true || t.tier === 'free' || owned.has(t.id)));
+    io.print(list.length ? list.map((t) => line(t, latestUsable(t, index), owned)).join('\n') : 'No starters match.');
+    io.print(`\nDetails: codz starters show <id>   Create: codz new <name> --template <id>`);
+    io.result({ templates: list.map((t) => ({ ...t, latest: latestUsable(t, index) })), catalog: { seq: index.seq, issued: index.issued, expires: index.expires, fromCache } });
+    return 0;
+}
+// ---------- Entry ----------
+export async function runStarterCommand(cmd, ctx) {
+    setAnnouncer((m) => ctx.io.warn(m));
+    switch (cmd) {
+        case 'new':
+            return runNew(ctx);
+        case 'starters':
+            return runStarters(ctx);
+        case 'login': {
+            if (process.env.CODZ_TOKEN)
+                ctx.io.warn('CODZ_TOKEN is set, so codz uses it instead of a login.');
+            const r = await auth.login({ print: (l) => ctx.io.print(l), browser: ctx.flags['no-browser'] !== true && !ctx.io.json });
+            ctx.io.print(`Logged in as ${r.account}.`);
+            ctx.io.result({ account: r.account });
+            return 0;
+        }
+        case 'logout': {
+            const r = await auth.logout();
+            if (process.env.CODZ_TOKEN)
+                ctx.io.warn('CODZ_TOKEN is still set in this environment; unset it, and revoke it from your web account if it leaked.');
+            ctx.io.print(r.removed ? `Logged out${r.revoked ? '' : ' on this machine (the server could not be reached; revoke the session from your web account if needed)'}.` : 'You were not logged in.');
+            ctx.io.result({ ...r });
+            return 0;
+        }
+        case 'whoami': {
+            const r = await auth.whoami();
+            ctx.io.print(`${r.account}`);
+            ctx.io.print(r.owned.length ? r.owned.map((o) => `  ${o.id}${o.updatesUntil ? `  (updates until ${o.updatesUntil})` : ''}`).join('\n') : '  No paid starters yet.');
+            ctx.io.result({ ...r });
+            return 0;
+        }
+    }
+    throw new ToolError('bad_args', `Unknown command "${cmd}".`);
+}
+export { undoNew };

package/dist/starters/engine.js

@@ -0,0 +1,315 @@
+// The starter engine: from a verified template and validated answers to a new
+// project folder. Offline and network-free; it cannot tell whether the
+// template came from the catalog, the cache or a folder on disk.
+//
+// Order: check requirements → build every file in memory (placeholders in
+// contents and paths, paths checked again) → preview → make a temporary folder
+// next to the target → run the before-move steps there (flutter create) →
+// write the files and the dependency entries → rename into place in one step →
+// run the after-move steps (pub get, format, npm install) → record history.
+// The target never exists half-built: any failure before the rename removes
+// the temporary folder.
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { appendHistory, newId, readHistory } from "../core/changeset.js";
+import { hash } from "../core/fsutil.js";
+import { jsonSet } from "../core/jsonEdit.js";
+import { ToolError } from "../core/types.js";
+import { placeholderValues, satisfies, STEP_ALLOWLIST } from "./manifest.js";
+import { checkCollisions, checkRelPath } from "./paths.js";
+import { runTool } from "../core/proc.js";
+const BINARY_EXT = /\.(png|jpe?g|gif|webp|ico|icns|bmp|ttf|otf|woff2?|eot|jar|keystore|jks|zip|gz|pdf|mp3|mp4|wav|webm|riv|lottie)$/i;
+export function isBinary(path, data) {
+    if (BINARY_EXT.test(path))
+        return true;
+    const n = Math.min(data.length, 8000);
+    for (let i = 0; i < n; i++)
+        if (data[i] === 0)
+            return true;
+    return false;
+}
+/** Plain string replacement of {{key}} for known keys only; anything else that looks like a placeholder is left alone. */
+export function substitute(text, values) {
+    return text.replace(/\{\{([a-zA-Z][a-zA-Z0-9]*(?:\.path)?)\}\}/g, (m, key) => values.get(key) ?? m);
+}
+function run(cmd, args, cwd, timeout = 15 * 60_000) {
+    // flutter and npm are .bat/.cmd files on Windows, which Node only starts through the shell. Every argument
+    // here is a fixed word or an answer that passed the identifier / reverse-domain checks, so nothing a shell
+    // would interpret can reach it.
+    for (const a of args)
+        if (!/^[A-Za-z0-9._\-=/]+$/.test(a))
+            throw new ToolError('internal', `Refusing to run ${cmd} with the argument "${a}".`);
+    const r = runTool(cmd, args, { cwd, timeout });
+    const missing = r.error?.code === 'ENOENT' || (process.platform === 'win32' && r.status === 1 && /not recognized/i.test(r.stderr ?? ''));
+    return { ok: r.status === 0, missing, output: `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() };
+}
+export function detectSdks(needFlutter) {
+    let flutter = null;
+    if (needFlutter) {
+        const r = run('flutter', ['--version', '--machine'], process.cwd(), 120_000);
+        if (r.ok) {
+            try {
+                flutter = JSON.parse(r.output.slice(r.output.indexOf('{'))).frameworkVersion ?? null;
+            }
+            catch {
+                flutter = /Flutter (\d+\.\d+\.\d+)/.exec(r.output)?.[1] ?? null;
+            }
+        }
+    }
+    return { flutter, node: process.version.replace(/^v/, '') };
+}
+// ---------- Planning ----------
+function stepCommand(id, answers) {
+    switch (id) {
+        case 'flutter_create':
+            return ['flutter', 'create', '--no-pub', '--org', String(answers.org), '--project-name', String(answers.appName), '.'];
+        case 'flutter_pub_get':
+            return ['flutter', 'pub', 'get'];
+        case 'dart_format':
+            return ['dart', 'format', '.'];
+        case 'npm_install':
+            return [process.platform === 'win32' ? 'npm.cmd' : 'npm', 'install', '--ignore-scripts', '--no-audit', '--no-fund'];
+    }
+}
+/** `sdks` null skips the SDK checks (publishing checks run without Flutter). */
+export function planNew(t, answers, parent, codzVersion, sdkInfo, opts) {
+    const sdks = sdkInfo ?? { flutter: '0.0.0', node: process.version.replace(/^v/, '') };
+    const checkSdks = sdkInfo !== null;
+    const m = t.manifest;
+    const warnings = [];
+    const target = resolve(parent, String(answers.appName));
+    if (m.requires.codz && !satisfies(codzVersion, m.requires.codz))
+        throw new ToolError('template_incompatible', `${m.id} ${m.version} needs codz ${m.requires.codz}; this is codz ${codzVersion}.`, 'Update codz, or pick an older version of the template.');
+    if (checkSdks && m.requires.node && !satisfies(sdks.node, m.requires.node))
+        throw new ToolError('template_incompatible', `${m.id} ${m.version} needs Node ${m.requires.node}; this is Node ${sdks.node}.`, 'Install a matching Node version, or pick another template version.');
+    const usesFlutter = m.framework === 'flutter';
+    if (checkSdks && usesFlutter && m.steps.includes('flutter_create') && !sdks.flutter)
+        throw new ToolError('sdk_missing', 'Flutter was not found, and this template is added on top of flutter create.', 'Install Flutter (flutter.dev), check it with codz doctor --setup, then run this again.');
+    if (checkSdks && usesFlutter && sdks.flutter && m.requires.flutter && !satisfies(sdks.flutter, m.requires.flutter))
+        throw new ToolError('template_incompatible', `${m.id} ${m.version} needs Flutter ${m.requires.flutter}; this is Flutter ${sdks.flutter}.`, 'Switch Flutter versions (for example with fvm), or pick another template version.');
+    if (checkSdks && usesFlutter && sdks.flutter && m.tested?.flutter?.length && !m.tested.flutter.some((v) => sdks.flutter.startsWith(v)))
+        warnings.push(`This template was tested with Flutter ${m.tested.flutter.join(', ')}; you have ${sdks.flutter}.`);
+    // Files, with placeholders filled in, and their paths checked again.
+    const values = placeholderValues(m, answers);
+    const files = [];
+    for (const f of m.files) {
+        const data = t.files.get(f.path);
+        const path = checkRelPath(substitute(f.path, values), 'template (after filling in answers)');
+        const out = isBinary(f.path, data) ? data : Buffer.from(substitute(data.toString('utf8'), values), 'utf8');
+        files.push({ path, data: out, mode: f.mode ?? '644' });
+    }
+    checkCollisions(files.map((f) => f.path), 'template (after filling in answers)');
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const steps = m.steps
+        .filter((id) => opts.steps || STEP_ALLOWLIST[id].when === 'before-move')
+        .map((id) => ({ id, label: STEP_ALLOWLIST[id].label, when: STEP_ALLOWLIST[id].when, command: stepCommand(id, answers) }));
+    if (checkSdks && usesFlutter && !sdks.flutter && steps.some((s) => s.id === 'flutter_pub_get' || s.id === 'dart_format'))
+        warnings.push('Flutter was not found, so flutter pub get and dart format will be skipped; run them yourself.');
+    return {
+        template: { id: m.id, version: m.version, title: m.title, origin: t.origin, archiveSha256: t.archiveSha256, manifestSha256: hash(t.manifestBytes.toString('utf8')), license: m.license.kind },
+        target,
+        answers,
+        files,
+        steps,
+        dependencies: m.dependencies ?? {},
+        devDependencies: m.devDependencies ?? {},
+        warnings,
+        apiAdd: m.apiAdd,
+    };
+}
+/** The preview: a folder tree of every file, the steps and the template identity. */
+export function renderPlan(p) {
+    const lines = [
+        `Template: ${p.template.id} ${p.template.version}${p.template.archiveSha256 ? ` (verified, archive ${p.template.archiveSha256.slice(0, 12)})` : ` (from ${p.template.origin}, files verified)`}`,
+        `License: ${p.template.license}`,
+        `Creates ${p.files.length} files in ${p.target}`,
+        '',
+    ];
+    const seen = new Set();
+    for (const f of p.files) {
+        const segs = f.path.split('/');
+        for (let i = 0; i < segs.length - 1; i++) {
+            const d = segs.slice(0, i + 1).join('/');
+            if (!seen.has(d)) {
+                seen.add(d);
+                lines.push(`${'  '.repeat(i)}${segs[i]}/`);
+            }
+        }
+        lines.push(`${'  '.repeat(segs.length - 1)}${segs[segs.length - 1]}${f.mode === '755' ? '  (executable)' : ''}`);
+    }
+    const deps = Object.entries(p.dependencies);
+    if (deps.length)
+        lines.push('', `Dependencies added: ${deps.map(([k, v]) => `${k} ${v}`).join(', ')}`);
+    if (p.steps.length)
+        lines.push('', 'Steps:', ...p.steps.map((s) => `  ${s.when === 'before-move' ? 'before' : 'after'}: ${s.command.join(' ')}`));
+    if (!p.apiAdd.supported)
+        lines.push('', `Note: codz api add does not support this starter${p.apiAdd.note ? ` (${p.apiAdd.note})` : ''}.`);
+    return lines.join('\n');
+}
+// ---------- Writing ----------
+/** Adds dependencies under `dependencies:` (or `dev_dependencies:`) in pubspec.yaml, after the SDK entries. */
+export function addPubspecEntries(text, section, deps) {
+    const lines = text.replace(/\r\n/g, '\n').split('\n');
+    const have = new Set();
+    let idx = lines.findIndex((l) => new RegExp(`^${section}:\\s*$`).test(l));
+    if (idx !== -1)
+        for (let i = idx + 1; i < lines.length && (/^\s/.test(lines[i]) || !lines[i].trim()); i++) {
+            const k = /^ {2}([A-Za-z0-9_]+):/.exec(lines[i])?.[1];
+            if (k)
+                have.add(k);
+        }
+    const missing = Object.keys(deps).filter((k) => !have.has(k)).sort();
+    if (!missing.length)
+        return text;
+    const entries = missing.map((k) => `  ${k}: ${/^[\^~<>=0-9]/.test(deps[k]) && !/[:#]/.test(deps[k]) ? deps[k] : JSON.stringify(deps[k])}`);
+    if (idx === -1) {
+        lines.push(...(lines[lines.length - 1] === '' ? [] : ['']), `${section}:`, ...entries, '');
+        return lines.join('\n');
+    }
+    let at = idx + 1;
+    while (/^ {2}\w+:\s*$/.test(lines[at] ?? '') && /^ {4}sdk:/.test(lines[at + 1] ?? ''))
+        at += 2;
+    lines.splice(at, 0, ...entries);
+    return lines.join('\n');
+}
+function addPackageJsonEntries(text, section, deps) {
+    let t = text;
+    const existing = JSON.parse(text)[section] ?? {};
+    for (const k of Object.keys(deps).sort())
+        if (!(k in existing))
+            t = jsonSet(t, [section, k], deps[k]);
+    return t;
+}
+/** Files that steps and later commands create and that never block undo. */
+const GENERATED = [/^\.dart_tool(\/|$)/, /^build(\/|$)/, /^\.flutter-plugins(-dependencies)?$/, /^pubspec\.lock$/, /^node_modules(\/|$)/, /^package-lock\.json$/, /^\.next(\/|$)/, /^\.codz(\/|$)/, /^codz\.config\.yaml$/, /^\.idea(\/|$)/, /^ios\/Pods(\/|$)/, /^ios\/Podfile\.lock$/, /^\.packages$/, /^next-env\.d\.ts$/, /^android\/local\.properties$/, /^android\/\.gradle(\/|$)/, /^\.metadata$/, /^.*\.iml$/];
+function listFiles(root, rel = '') {
+    const out = [];
+    for (const name of readdirSync(join(root, rel)).sort()) {
+        const p = rel ? `${rel}/${name}` : name;
+        if (GENERATED.some((g) => g.test(p)))
+            continue;
+        const st = lstatSync(join(root, p));
+        if (st.isDirectory())
+            out.push(...listFiles(root, p));
+        else if (st.isFile())
+            out.push(p);
+    }
+    return out;
+}
+export function applyNew(p, log = () => { }) {
+    if (existsSync(p.target) && readdirSync(p.target).length)
+        throw new ToolError('dir_not_empty', `${p.target} already exists and is not empty.`, 'Pick another name, or remove that folder.');
+    const parent = dirname(p.target);
+    mkdirSync(parent, { recursive: true });
+    const tmp = join(parent, `.${basename(p.target)}.codz-new-${randomBytes(4).toString('hex')}`);
+    mkdirSync(tmp);
+    const warnings = [...p.warnings];
+    const stepResults = [];
+    try {
+        for (const s of p.steps.filter((x) => x.when === 'before-move')) {
+            log(`Running ${s.command.join(' ')}...`);
+            const r = run(s.command[0], s.command.slice(1), tmp);
+            if (!r.ok)
+                throw new ToolError(r.missing ? 'sdk_missing' : 'step_failed', `${s.command.join(' ')} ${r.missing ? 'was not found' : 'failed'}, so nothing was created.${r.output ? `\n${r.output.split('\n').slice(-5).join('\n')}` : ''}`, r.missing ? 'Install the SDK; check it with codz doctor --setup.' : 'Fix the problem above and run this again.');
+            stepResults.push({ id: s.id, ok: true });
+        }
+        for (const f of p.files) {
+            const abs = join(tmp, f.path);
+            mkdirSync(dirname(abs), { recursive: true });
+            writeFileSync(abs, f.data);
+            if (f.mode === '755')
+                chmodSync(abs, 0o755);
+        }
+        const deps = p.dependencies;
+        const dev = p.devDependencies;
+        if (Object.keys(deps).length || Object.keys(dev).length) {
+            const pubspec = join(tmp, 'pubspec.yaml');
+            const pkg = join(tmp, 'package.json');
+            if (existsSync(pubspec)) {
+                let t = readFileSync(pubspec, 'utf8');
+                t = addPubspecEntries(t, 'dependencies', deps);
+                t = addPubspecEntries(t, 'dev_dependencies', dev);
+                writeFileSync(pubspec, t);
+            }
+            else if (existsSync(pkg)) {
+                let t = readFileSync(pkg, 'utf8');
+                t = addPackageJsonEntries(t, 'dependencies', deps);
+                t = addPackageJsonEntries(t, 'devDependencies', dev);
+                writeFileSync(pkg, t);
+            }
+            else
+                warnings.push('The template lists dependencies but has no pubspec.yaml or package.json to add them to.');
+        }
+        if (existsSync(p.target))
+            rmSync(p.target, { recursive: true, force: true }); // an empty folder only (checked above)
+        renameSync(tmp, p.target);
+    }
+    catch (e) {
+        rmSync(tmp, { recursive: true, force: true });
+        throw e;
+    }
+    for (const s of p.steps.filter((x) => x.when === 'after-move')) {
+        log(`Running ${s.command.join(' ')}...`);
+        const r = run(s.command[0], s.command.slice(1), p.target);
+        if (r.ok)
+            stepResults.push({ id: s.id, ok: true });
+        else {
+            const note = `${s.command.join(' ')} ${r.missing ? 'was not found' : 'failed'}; the project was created. Run it yourself in ${basename(p.target)}/.`;
+            stepResults.push({ id: s.id, ok: false, note });
+            warnings.push(note);
+        }
+    }
+    // History in the new project, so codz undo there removes it again.
+    const id = newId();
+    const recorded = listFiles(p.target);
+    appendHistory(p.target, {
+        id,
+        skill: 'new',
+        summary: [`Create ${basename(p.target)} from ${p.template.id} ${p.template.version}`],
+        files: recorded.map((f) => ({ path: f, created: true, afterHash: hash(readFileSync(join(p.target, f), 'utf8')) })),
+        generated: [],
+        undone: false,
+        meta: { starter: { id: p.template.id, version: p.template.version, archiveSha256: p.template.archiveSha256 ?? null, manifestSha256: p.template.manifestSha256, origin: p.template.archiveSha256 ? 'catalog' : 'folder' }, answers: p.answers, target: p.target },
+    });
+    return { id, target: p.target, files: recorded.length, steps: stepResults, warnings };
+}
+// ---------- Undo ----------
+/** The last change in this project, when it is the codz new that created it. */
+export function lastNewEntry(root) {
+    const e = [...readHistory(root)].reverse().find((x) => !x.undone);
+    return e && e.skill === 'new' ? e : null;
+}
+/**
+ * Removes a project codz new created, when nothing in it changed since.
+ * Generated files (pub get, npm install, codz init) do not count as changes;
+ * any other edit or new file blocks it unless `force`.
+ */
+export function undoNew(root, opts = {}) {
+    const entry = lastNewEntry(root);
+    if (!entry)
+        throw new ToolError('nothing_to_undo', 'The last change here was not codz new.');
+    const target = resolve(String(entry.meta?.target ?? ''));
+    if (target !== resolve(root))
+        throw new ToolError('changed_since_apply', `This project was created at ${target}, not here, so codz will not delete it.`, 'Delete the folder yourself if you no longer want it.');
+    const recorded = new Map(entry.files.map((f) => [f.path, f.afterHash]));
+    const now = listFiles(root);
+    const changed = [
+        ...entry.files.filter((f) => !existsSync(join(root, f.path)) || hash(readFileSync(join(root, f.path), 'utf8')) !== f.afterHash).map((f) => f.path),
+        ...now.filter((f) => !recorded.has(f) && !(f === '.gitignore')),
+    ];
+    // codz init adds .codz/ to .gitignore; that alone does not count.
+    const gi = recorded.get('.gitignore');
+    const idx = changed.indexOf('.gitignore');
+    if (idx !== -1 && gi && existsSync(join(root, '.gitignore'))) {
+        const t = readFileSync(join(root, '.gitignore'), 'utf8');
+        const without = t.replace(/\n?# codz cache, backups and history\n\.codz\/\n$/, '');
+        if (hash(without) === gi || hash(`${without}\n`) === gi)
+            changed.splice(idx, 1);
+    }
+    if (changed.length && !opts.force) {
+        throw new ToolError('changed_since_apply', `These files changed after codz created the project: ${changed.slice(0, 8).join(', ')}${changed.length > 8 ? ', ...' : ''}. Undo would delete those edits.`, 'Keep your edits, or pass --force to delete the whole project anyway.');
+    }
+    rmSync(root, { recursive: true, force: true });
+    return { id: entry.id, removed: root };
+}

package/dist/starters/home.js

@@ -0,0 +1,42 @@
+// codz's per-user folder (~/.codz, or CODZ_HOME): the login token,
+// the last signed catalog index and the cache of verified starter archives.
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export function codzHome() {
+    return process.env.CODZ_HOME || join(homedir(), '.codz');
+}
+export function homePath(...parts) {
+    return join(codzHome(), ...parts);
+}
+export function readHomeFile(...parts) {
+    try {
+        return readFileSync(homePath(...parts));
+    }
+    catch {
+        return null;
+    }
+}
+/** Writes atomically (temporary name, then rename). `secret` files are readable by the owner only. */
+export function writeHomeFile(data, opts, ...parts) {
+    const path = homePath(...parts);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, data, { mode: opts.secret ? 0o600 : 0o644 });
+    if (opts.secret) {
+        try {
+            chmodSync(tmp, 0o600);
+        }
+        catch {
+            // Windows has no POSIX modes; the file is in the user's profile folder.
+        }
+    }
+    renameSync(tmp, path);
+}
+export function removeHome(...parts) {
+    const path = homePath(...parts);
+    if (!existsSync(path))
+        return false;
+    rmSync(path, { recursive: true, force: true });
+    return true;
+}