codz-cli 0.0.0-stage → 0.1.2

package/dist/core/cache.js

@@ -0,0 +1,76 @@
+// The project map is a cache rebuilt from the code. It lives in .codz/
+// (git-ignored) and is refreshed before every skill when files changed.
+import { mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { hash, readJson, readText, walk } from "./fsutil.js";
+import { MAP_SCHEMA_VERSION } from "./types.js";
+export const TOOL_DIR = '.codz';
+const FINGERPRINT_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.json', '.dart', '.yaml', '.yml', '.arb', '.env', '.example', '.local'];
+/**
+ * codz's own source, so a map scanned by an older codz is rebuilt after an
+ * upgrade even when the version number did not change.
+ */
+let toolBuild;
+function toolFingerprint() {
+    if (toolBuild)
+        return toolBuild;
+    const src = join(dirname(fileURLToPath(import.meta.url)), '..');
+    // src/*.ts when run from source, dist/*.js when installed from npm.
+    const parts = walk(src, '.', { exts: import.meta.url.endsWith('.ts') ? ['.ts'] : ['.js'] }).map((f) => {
+        const st = statSync(join(src, f));
+        return `${f}:${st.size}:${Math.floor(st.mtimeMs)}`;
+    });
+    return (toolBuild = hash(parts.join('\n')));
+}
+/** Read-only runs (--dry-run, doctor) scan in memory and leave .codz/ alone. */
+let cacheWrites = true;
+export function setCacheWrites(on) {
+    cacheWrites = on;
+}
+export function toolDir(root, ...parts) {
+    const dir = join(root, TOOL_DIR, ...parts);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/** Cheap fingerprint of the project: path, size and modified time of relevant files. */
+export function fingerprint(root, configText) {
+    const files = walk(root, '.', { exts: FINGERPRINT_EXTS });
+    const parts = [configText];
+    for (const f of files) {
+        try {
+            const st = statSync(join(root, f));
+            parts.push(`${f}:${st.size}:${Math.floor(st.mtimeMs)}`);
+        }
+        catch {
+            // File vanished during the walk; skip it.
+        }
+    }
+    return hash(parts.join('\n'));
+}
+export async function loadMap(root, adapter, conventions, opts = {}) {
+    const cachePath = join(root, TOOL_DIR, 'cache', 'map.json');
+    const configText = readText(join(root, 'codz.config.yaml')) ?? '';
+    const fp = fingerprint(root, configText);
+    const cached = readJson(cachePath);
+    if (!opts.force && cached && cached.schema === MAP_SCHEMA_VERSION && cached.adapter === `${adapter.id}@${adapter.version}` && cached.tool === toolFingerprint() && cached.fingerprint === fp) {
+        return { map: cached.map, fromCache: true };
+    }
+    // An old schema or adapter version is simply rebuilt, never migrated.
+    const map = await adapter.scan(root, conventions);
+    const file = { schema: MAP_SCHEMA_VERSION, adapter: `${adapter.id}@${adapter.version}`, tool: toolFingerprint(), fingerprint: fp, map };
+    if (cacheWrites) {
+        toolDir(root, 'cache');
+        writeFileSync(cachePath, JSON.stringify(file, null, 2));
+    }
+    return { map, fromCache: false };
+}
+export function invalidateMap(root) {
+    const cachePath = join(root, TOOL_DIR, 'cache', 'map.json');
+    try {
+        writeFileSync(cachePath, '{}');
+    }
+    catch {
+        // No cache yet.
+    }
+}

package/dist/core/changeset.js

@@ -0,0 +1,404 @@
+// Change sets: plan, preview, apply (with hash checks, atomic writes,
+// backups, formatting and verification) and undo.
+import { fileHeader } from "./templates.js";
+import { randomBytes } from 'node:crypto';
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { invalidateMap, toolDir, TOOL_DIR } from "./cache.js";
+import { diffStats, unifiedDiff } from "./diff.js";
+import { exists, hash, readJson, readText } from "./fsutil.js";
+import { dirtyFiles, isGitRepo } from "./git.js";
+import { ToolError } from "./types.js";
+import { runTool, toolMissing } from "./proc.js";
+export function newId() {
+    const d = new Date();
+    const stamp = `${d.getUTCFullYear()}${String(d.getUTCMonth() + 1).padStart(2, '0')}${String(d.getUTCDate()).padStart(2, '0')}-${String(d.getUTCHours()).padStart(2, '0')}${String(d.getUTCMinutes()).padStart(2, '0')}${String(d.getUTCSeconds()).padStart(2, '0')}`;
+    return `${stamp}-${randomBytes(3).toString('hex')}`;
+}
+function safePath(root, relPath) {
+    const abs = resolve(root, relPath);
+    const r = resolve(root);
+    if (abs !== r && !abs.startsWith(r + '/') && !abs.startsWith(r + '\\')) {
+        throw new ToolError('outside_root', `Refusing to touch ${relPath}: it is outside the project root.`);
+    }
+    if (relPath.split(/[\\/]/).includes(TOOL_DIR))
+        throw new ToolError('outside_root', `Refusing to edit codz's own folder (${relPath}).`);
+    // Lexical checks are not enough: a symbolic link inside the project (for example lib -> ~/.ssh) would carry the
+    // write outside it. Resolve the deepest folder that exists and check that it is still inside the real root.
+    const realRoot = realpathSync(r);
+    let probe = abs;
+    while (!existsSync(probe) && dirname(probe) !== probe)
+        probe = dirname(probe);
+    if (existsSync(abs) && lstatSync(abs).isSymbolicLink())
+        throw new ToolError('outside_root', `Refusing to touch ${relPath}: it is a symbolic link.`, 'Replace the link with a real file, or run codz on the folder it points to.');
+    const realProbe = realpathSync(probe);
+    if (realProbe !== realRoot && !realProbe.startsWith(realRoot + sep)) {
+        throw new ToolError('outside_root', `Refusing to touch ${relPath}: a symbolic link takes it outside the project root.`);
+    }
+    return abs;
+}
+export function buildChangeSet(root, skill, edits) {
+    const changes = [];
+    const entries = [...edits.files.entries(), ...[...(edits.deletes ?? [])].filter((p) => !edits.files.has(p)).map((p) => [p, null])];
+    for (let [path, after] of entries.sort(([a], [b]) => a.localeCompare(b))) {
+        const abs = safePath(root, path);
+        const before = readText(abs);
+        if (before === after)
+            continue; // also skips deleting a file that does not exist
+        // New files start with the project's header template, if it has one.
+        if (before === null && after !== null) {
+            const header = fileHeader(root, path);
+            if (header && !after.startsWith(header))
+                after = header + after;
+        }
+        changes.push({ path, baseHash: before === null ? null : hash(before), before, after });
+    }
+    const rewrites = (edits.rewrites ?? []).filter((p) => changes.some((c) => c.path === p));
+    return { id: newId(), skill, summary: edits.summary, warnings: edits.warnings, changes, generated: edits.generated, ...(rewrites.length ? { rewrites } : {}) };
+}
+/** Lines that say something (not blank, not a lone bracket), trimmed. */
+const meaningful = (text) => text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 3);
+/**
+ * Files an edit would mostly replace: an existing file where less than half of
+ * its lines survive. Commands edit existing files at known places (an import,
+ * a route, a dependency) and keep the rest, so this means a generator wrote a
+ * whole new file over one it should only have edited (as when a login page once
+ * replaced a GetX binding). Files a command replaces on purpose are listed in
+ * cs.rewrites and allowed.
+ */
+export function rewriteProblems(cs) {
+    const allowed = new Set(cs.rewrites ?? []);
+    const out = [];
+    for (const c of cs.changes) {
+        if (c.before === null || c.after === null || allowed.has(c.path))
+            continue;
+        const before = meaningful(c.before);
+        if (before.length < 4)
+            continue;
+        const after = new Set(meaningful(c.after));
+        const kept = before.filter((l) => after.has(l)).length;
+        if (kept / before.length < 0.5)
+            out.push(c.path);
+    }
+    return out;
+}
+export function renderDiff(cs, color) {
+    return cs.changes.map((c) => unifiedDiff(c.path, c.before, c.after, { color })).join('\n');
+}
+export function changeSetJson(cs, includeDiff = true) {
+    return {
+        id: cs.id,
+        skill: cs.skill,
+        summary: cs.summary,
+        warnings: cs.warnings,
+        files: cs.changes.map((c) => ({
+            path: c.path,
+            action: c.before === null ? 'create' : c.after === null ? 'delete' : 'modify',
+            ...diffStats(c.before, c.after),
+            ...(includeDiff ? { diff: unifiedDiff(c.path, c.before, c.after) } : {}),
+        })),
+    };
+}
+// ---------- Plans (preview now, apply exactly this later) ----------
+export function savePlan(root, cs) {
+    const dir = toolDir(root, 'plans');
+    writeFileSync(join(dir, `${cs.id}.json`), JSON.stringify(cs, null, 2));
+    return cs.id;
+}
+export function loadPlan(root, id) {
+    const cs = readJson(join(root, TOOL_DIR, 'plans', `${id}.json`));
+    if (!cs)
+        throw new ToolError('no_plan', `No saved plan with id "${id}".`, 'Run the skill again with --plan to create one.');
+    return cs;
+}
+function historyPath(root) {
+    return join(toolDir(root), 'history.json');
+}
+export function readHistory(root) {
+    return readJson(historyPath(root)) ?? [];
+}
+function writeHistory(root, entries) {
+    writeFileSync(historyPath(root), JSON.stringify(entries, null, 2));
+}
+/** Records a change made outside applyChangeSet (codz new writes a whole project). */
+export function appendHistory(root, entry) {
+    writeHistory(root, [...readHistory(root), entry]);
+}
+/** Marks a history entry as undone. */
+export function markUndone(root, id) {
+    const h = readHistory(root);
+    const e = h.find((x) => x.id === id);
+    if (e) {
+        e.undone = true;
+        writeHistory(root, h);
+    }
+}
+function run(cmd, args, cwd) {
+    const r = runTool(cmd, args, { cwd, timeout: 180_000 });
+    if (toolMissing(r))
+        return { ok: false, output: '', missing: true };
+    return { ok: r.status === 0, output: `${r.stdout ?? ''}${r.stderr ?? ''}`, missing: false };
+}
+/** Counts analyzer error lines per changed file. */
+function errorCounts(output, files) {
+    const counts = new Map();
+    for (const line of output.split('\n')) {
+        if (!/error/i.test(line))
+            continue;
+        for (const f of files) {
+            if (line.includes(f))
+                counts.set(f, (counts.get(f) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+/** A lock older than this is from a run that died; it is taken over. */
+const LOCK_STALE_MS = 10 * 60 * 1000;
+/**
+ * Runs fn holding .codz/lock, so two codz runs on one project (a person and
+ * an AI agent, two terminals) cannot apply or undo at the same time and mix their
+ * files and backups. A lock left by a process that is gone, or an old one, is taken over.
+ */
+export function withProjectLock(root, fn) {
+    const dir = join(root, TOOL_DIR);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, 'lock');
+    for (let attempt = 0;; attempt++) {
+        try {
+            const fd = openSync(file, 'wx');
+            writeSync(fd, JSON.stringify({ pid: process.pid, started: new Date().toISOString() }));
+            closeSync(fd);
+            break;
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST' || attempt > 0) {
+                if (e.code === 'EEXIST')
+                    throw new ToolError('busy', 'Another codz change is being applied or undone in this project.', 'Wait for it to finish and try again.');
+                throw e;
+            }
+            let held = {};
+            try {
+                held = JSON.parse(readFileSync(file, 'utf8'));
+            }
+            catch {
+                held = {};
+            }
+            const alive = (() => {
+                if (!held.pid || held.pid === process.pid)
+                    return held.pid === process.pid;
+                try {
+                    process.kill(held.pid, 0);
+                    return true;
+                }
+                catch (err) {
+                    return err.code === 'EPERM';
+                }
+            })();
+            const old = !held.started || Date.now() - Date.parse(held.started) > LOCK_STALE_MS;
+            if (alive && !old)
+                throw new ToolError('busy', `Another codz run (process ${held.pid}) is applying or undoing a change in this project.`, 'Wait for it to finish and try again.');
+            rmSync(file, { force: true });
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        rmSync(file, { force: true });
+    }
+}
+export function applyChangeSet(root, cs, opts = {}) {
+    if (cs.changes.length === 0)
+        return { files: [], formatted: false, verified: false };
+    return withProjectLock(root, () => applyLocked(root, cs, opts));
+}
+function applyLocked(root, cs, opts) {
+    if (!opts.allowDirty && isGitRepo(root)) {
+        const dirty = dirtyFiles(root).filter((f) => f !== 'codz.config.yaml');
+        if (dirty.length) {
+            throw new ToolError('dirty_git', `The working tree has uncommitted changes (${dirty.slice(0, 5).join(', ')}${dirty.length > 5 ? ', ...' : ''}).`, 'Commit or stash them first, or pass --allow-dirty. Undo still works either way, from codz backups.');
+        }
+    }
+    // A generator must not write a whole new file over one it should only edit.
+    const replaced = rewriteProblems(cs);
+    if (replaced.length && !opts.allowRewrite) {
+        throw new ToolError('unsafe_rewrite', `This change would replace most of ${replaced.join(', ')} instead of editing ${replaced.length === 1 ? 'it' : 'them'}, so nothing was applied.`, 'This is a codz bug: please report it with the command you ran. Check the preview with --dry-run.');
+    }
+    // Every target must be exactly as it was when the change set was planned.
+    for (const c of cs.changes) {
+        const current = readText(safePath(root, c.path));
+        const currentHash = current === null ? null : hash(current);
+        if (currentHash !== c.baseHash) {
+            throw new ToolError('changed_since_plan', `${c.path} changed after the preview was made, so nothing was applied.`, 'Run the skill again to get a fresh preview.');
+        }
+    }
+    const files = cs.changes.filter((c) => c.after !== null).map((c) => c.path);
+    const verifyCmd = opts.verify !== false ? opts.adapter?.verifyCommand?.(root, files) : null;
+    let baseline = new Map();
+    if (verifyCmd) {
+        const existing = cs.changes.filter((c) => c.before !== null).map((c) => c.path);
+        if (existing.length) {
+            const before = run(verifyCmd.cmd, verifyCmd.args, root);
+            if (!before.missing)
+                baseline = errorCounts(before.output, files);
+        }
+    }
+    // Back up originals.
+    const backupDir = toolDir(root, 'backups', cs.id);
+    for (const c of cs.changes) {
+        if (c.before !== null) {
+            const dest = join(backupDir, c.path);
+            mkdirSync(dirname(dest), { recursive: true });
+            writeFileSync(dest, c.before);
+        }
+    }
+    // Write all files to temporary names first, then swap them in.
+    const temps = [];
+    try {
+        for (const c of cs.changes) {
+            if (c.after === null)
+                continue;
+            const abs = safePath(root, c.path);
+            mkdirSync(dirname(abs), { recursive: true });
+            const tmp = `${abs}.codz-tmp`;
+            writeFileSync(tmp, c.after);
+            temps.push({ tmp, abs });
+        }
+        for (const t of temps)
+            renameSync(t.tmp, t.abs);
+        for (const c of cs.changes)
+            if (c.after === null)
+                unlinkSync(safePath(root, c.path));
+    }
+    catch (e) {
+        for (const t of temps)
+            if (exists(t.tmp))
+                rmSync(t.tmp, { force: true });
+        restore(root, cs.id, cs.changes.map((c) => ({ path: c.path, created: c.before === null, deleted: c.after === null })));
+        throw new ToolError('write_failed', `Writing files failed, and everything was restored: ${e.message}`);
+    }
+    const result = { files, formatted: false, verified: false };
+    if (opts.format !== false) {
+        const fmt = opts.adapter?.formatCommand?.(root, files);
+        if (fmt) {
+            const r = run(fmt.cmd, fmt.args, root);
+            if (r.missing)
+                result.formatNote = `Formatter "${fmt.cmd}" was not found, so files were left as generated.`;
+            else if (!r.ok)
+                result.formatNote = `Formatter "${fmt.cmd}" reported a problem; files were left as generated. ${r.output.trim().split('\n')[0] ?? ''}`;
+            else
+                result.formatted = true;
+        }
+    }
+    if (verifyCmd) {
+        const after = run(verifyCmd.cmd, verifyCmd.args, root);
+        if (after.missing) {
+            result.verifyNote = `Analyzer "${verifyCmd.cmd}" was not found, so the result was not checked.`;
+        }
+        else {
+            const counts = errorCounts(after.output, files);
+            const worse = files.filter((f) => (counts.get(f) ?? 0) > (baseline.get(f) ?? 0));
+            if (worse.length) {
+                restore(root, cs.id, cs.changes.map((c) => ({ path: c.path, created: c.before === null, deleted: c.after === null })));
+                const lines = after.output.split('\n').filter((l) => worse.some((f) => l.includes(f)) && /error/i.test(l)).slice(0, 8);
+                throw new ToolError('verify_failed', `The analyzer found new errors in ${worse.join(', ')}, so the change was reverted.\n${lines.join('\n')}`, 'Run with --no-verify to apply anyway and fix the errors by hand.');
+            }
+            result.verified = true;
+        }
+    }
+    const history = readHistory(root);
+    history.push({
+        id: cs.id,
+        skill: cs.skill,
+        summary: cs.summary,
+        files: cs.changes.map((c) => (c.after === null ? { path: c.path, created: false, deleted: true, afterHash: '' } : { path: c.path, created: c.before === null, afterHash: hash(readText(safePath(root, c.path)) ?? '') })),
+        generated: cs.generated,
+        undone: false,
+    });
+    writeHistory(root, history);
+    invalidateMap(root);
+    return result;
+}
+function restore(root, id, files) {
+    const backupDir = join(root, TOOL_DIR, 'backups', id);
+    for (const f of files) {
+        const abs = safePath(root, f.path);
+        if (f.created) {
+            if (exists(abs))
+                unlinkSync(abs);
+            // Folders the change created (lib/features/orders/) go too, once they are empty; never the project root.
+            for (let dir = dirname(abs); dir.startsWith(resolve(root) + sep); dir = dirname(dir)) {
+                try {
+                    if (readdirSync(dir).length)
+                        break;
+                    rmdirSync(dir);
+                }
+                catch {
+                    break;
+                }
+            }
+        }
+        else {
+            const original = readText(join(backupDir, f.path));
+            if (original !== null) {
+                mkdirSync(dirname(abs), { recursive: true });
+                writeFileSync(abs, original);
+            }
+        }
+    }
+}
+export function undoLast(root, opts = {}) {
+    return withProjectLock(root, () => undoLastLocked(root, opts));
+}
+function undoLastLocked(root, opts) {
+    const history = readHistory(root);
+    const entry = [...history].reverse().find((e) => !e.undone);
+    if (!entry)
+        throw new ToolError('nothing_to_undo', 'There is nothing to undo.');
+    const changed = entry.files.filter((f) => {
+        const current = readText(safePath(root, f.path));
+        if (f.deleted)
+            return current !== null; // something new was written where codz deleted a file
+        return current === null || hash(current) !== f.afterHash;
+    });
+    if (changed.length && !opts.force) {
+        throw new ToolError('changed_since_apply', `These files changed after codz wrote them: ${changed.map((f) => f.path).join(', ')}. Undo would lose those edits.`, 'Pass --force to undo anyway.');
+    }
+    restore(root, entry.id, entry.files);
+    entry.undone = true;
+    writeHistory(root, history);
+    invalidateMap(root);
+    return { id: entry.id, skill: entry.skill, files: entry.files.map((f) => f.path) };
+}
+/** Undoes changes from the newest back to (and including) `id`. Stops at the first conflict. */
+export function undoTo(root, id, opts = {}) {
+    const history = readHistory(root);
+    const target = history.find((e) => e.id === id || e.id.startsWith(id));
+    if (!target)
+        throw new ToolError('no_change', `No applied change with id "${id}".`, 'List them with: codz history');
+    if (target.undone)
+        throw new ToolError('already_undone', `${target.id} is already undone.`);
+    const done = [];
+    for (;;) {
+        const r = undoLast(root, opts);
+        done.push(r);
+        if (r.id === target.id)
+            return done;
+    }
+}
+/** One applied change: its files, whether each still matches what codz wrote, and the diff it made. */
+export function historyShow(root, id) {
+    const entry = readHistory(root).find((e) => e.id === id || e.id.startsWith(id));
+    if (!entry)
+        throw new ToolError('no_change', `No applied change with id "${id}".`, 'List them with: codz history');
+    const backupDir = join(root, TOOL_DIR, 'backups', entry.id);
+    const files = entry.files.map((f) => {
+        const current = readText(safePath(root, f.path));
+        const before = f.created ? null : readText(join(backupDir, f.path));
+        const action = f.created ? 'created' : f.deleted ? 'deleted' : 'changed';
+        const state = f.deleted ? (current === null ? 'as applied' : 'edited since') : current === null ? 'missing' : hash(current) === f.afterHash ? 'as applied' : 'edited since';
+        const after = f.deleted ? null : state === 'as applied' ? current : null;
+        return { path: f.path, action, state, diff: state === 'as applied' || f.deleted ? unifiedDiff(f.path, before, after) : undefined };
+    });
+    return { entry, files };
+}