@cspeach/cli 1.1.30 → 1.1.32

package/dist/projects/sort-command.js

@@ -0,0 +1,499 @@
+/**
+ * 2026-10-08 (sessions/folders, Task 13) — `cspeach files sort`.
+ *
+ *   cspeach files sort                 list old project files with a likely
+ *                                      folder; write <cwd>/sort-plan.json
+ *   cspeach files sort --apply <plan>  COPY each placed file (and a plan's
+ *                                      lane file + spec-gap) into
+ *                                      <folder>/.cspeach/, check every copy
+ *                                      by sha256; never delete
+ *   cspeach files sort --clean <plan>  after one confirm, delete only the
+ *                                      originals whose copy checks
+ *
+ * Data safety: copy only; never overwrite a different file (report, skip);
+ * a chain of linked files is copied whole or not at all; only top-level
+ * *.cspeach.json files in the old save locations and a plan's own linked
+ * files are read or copied; session files are never touched (the session
+ * backfill runs first, as at start-up). The plan file is untrusted on
+ * --apply / --clean and is checked again.
+ */
+import { createHash } from 'node:crypto';
+import { constants as fsc, promises as fs, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { cspeachRoot, sessionsDir } from '../config/paths.js';
+import { backfillSessionFolders } from '../session/backfill.js';
+import { normDir } from '../session/project-match.js';
+import { canonicalLanePath, isLanePath } from '../lane/paths.js';
+import { ensureProjectId, legacyDirsFor } from './project-folder.js';
+import { buildSortPlan, insideCliHome, linkChains, linkedFileCandidates } from './sort-core.js';
+/**
+ * Task 14 — the folder a copy lands in, judged by its REAL path (nearest
+ * existing ancestor realpath'd, links followed; never a cached lookup, the
+ * folder may have changed since): a link deeper in the target
+ * (`<target>/.cspeach/lane` → the CLI home) is caught. Unknown → refused.
+ */
+function destInCliHome(dest) {
+    let cur = path.dirname(path.resolve(dest));
+    const tail = [];
+    for (;;) {
+        try {
+            const real = realpathSync.native(cur);
+            return insideCliHome(tail.length ? path.join(real, ...tail) : real);
+        }
+        catch (e) {
+            if (e?.code !== 'ENOENT')
+                return true;
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                return true;
+            tail.unshift(path.basename(cur));
+            cur = parent;
+        }
+    }
+}
+const ENVELOPE = /\.cspeach\.json$/i;
+const PLAN_NAME = 'sort-plan.json';
+const USAGE = 'Usage: cspeach files sort [--apply <plan>] [--clean <plan>]';
+export async function runFilesSort(args, io) {
+    if (args.length === 0)
+        return suggest(io);
+    if (args.length === 2 && args[0] === '--apply')
+        return apply(path.resolve(io.cwd, args[1]), io);
+    if (args.length === 2 && args[0] === '--clean')
+        return clean(path.resolve(io.cwd, args[1]), io);
+    io.log(USAGE);
+    return 1;
+}
+/* ── reading ────────────────────────────────────────────────────────────── */
+async function sha256(file) {
+    return createHash('sha256').update(await fs.readFile(file)).digest('hex');
+}
+/** A regular file (not a link, not a folder). */
+async function isPlainFile(p) {
+    try {
+        return (await fs.lstat(p)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function isFolder(p) {
+    try {
+        return (await fs.stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Top-level *.cspeach.json files in the old save locations. */
+async function scanSources(dirs) {
+    const out = [];
+    for (const dir of dirs) {
+        let names;
+        try {
+            names = await fs.readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names.filter((n) => ENVELOPE.test(n)).sort()) {
+            const p = path.join(dir, name);
+            let st;
+            try {
+                st = await fs.lstat(p);
+            }
+            catch {
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            let env = null;
+            try {
+                env = JSON.parse(stripBom(await fs.readFile(p, 'utf8')));
+            }
+            catch { /* unreadable: listed low */ }
+            out.push({ path: p, env: env && typeof env === 'object' && !Array.isArray(env) ? env : null, mtimeMs: st.mtimeMs });
+        }
+    }
+    return out;
+}
+const stripBom = (s) => (s.charCodeAt(0) === 0xfeff ? s.slice(1) : s);
+/** Every session file, parsed; corrupt and reader files skipped. Read only. */
+async function loadSessions() {
+    const dir = sessionsDir();
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names) {
+        if (!n.endsWith('.json') || n.startsWith('.') || n.includes('-reader-'))
+            continue;
+        try {
+            const s = JSON.parse(await fs.readFile(path.join(dir, n), 'utf8'));
+            if (s && typeof s === 'object' && !Array.isArray(s))
+                out.push(s);
+        }
+        catch { /* corrupt: skip */ }
+    }
+    return out;
+}
+/**
+ * Write the plan without touching an earlier one the person may have edited:
+ * sort-plan.json, else sort-plan-2.json, sort-plan-3.json, ...
+ */
+async function writeNewPlanFile(dir, text) {
+    for (let n = 1;; n++) {
+        const out = path.join(dir, n === 1 ? PLAN_NAME : `sort-plan-${n}.json`);
+        try {
+            await fs.writeFile(out, text, { encoding: 'utf8', flag: 'wx' });
+            return out;
+        }
+        catch (e) {
+            if (e?.code !== 'EEXIST' || n >= 999)
+                throw e;
+        }
+    }
+}
+/* ── suggest ────────────────────────────────────────────────────────────── */
+async function suggest(io) {
+    await backfillSessionFolders().catch(() => { });
+    const sources = legacyDirsFor(io.cwd);
+    const files = await scanSources(sources);
+    if (files.length === 0) {
+        io.log('No project files from earlier builds were found.');
+        return 0;
+    }
+    const sessions = await loadSessions();
+    const projectDirs = sessions
+        .map((s) => s.project_dir)
+        .filter((d) => typeof d === 'string' && d !== '');
+    const rows = buildSortPlan({ files, sessions, projectDirs });
+    const created = new Map(files.map((f) => [f.path, String(f.env?.createdAt ?? '').slice(0, 10) || '?']));
+    io.log(`${files.length} project file${files.length === 1 ? '' : 's'} from earlier builds, in: ${sources.join(', ')}`);
+    io.log('');
+    const table = [
+        ['file', 'created', 'chain', 'likely folder', 'confidence (why)'],
+        ...rows.map((r) => [path.basename(r.file), created.get(r.file) ?? '?', r.chain, r.target ?? '?', `${r.confidence} (${r.why})`]),
+    ];
+    const widths = table[0].map((_, c) => Math.max(...table.map((row) => row[c].length)));
+    for (const row of table)
+        io.log(row.map((cell, c) => (c === row.length - 1 ? cell : cell.padEnd(widths[c]))).join('  '));
+    io.log('');
+    const out = await writeNewPlanFile(io.cwd, `${JSON.stringify(rows, null, 2)}\n`);
+    io.log(`Saved the plan to ${out}.`);
+    io.log('Check each "target". Change it to another full folder path, or set it to null to leave a file where it is.');
+    io.log(`Then run: cspeach files sort --apply ${out}`);
+    io.log('Files are copied. Nothing is moved or deleted.');
+    return 0;
+}
+/** A full folder path: on Windows it must start with a drive (`C:\`) or a share (`\\server`). */
+function isFullPath(p) {
+    if (!path.isAbsolute(p))
+        return false;
+    return process.platform !== 'win32' || /^[A-Za-z]:[\\/]/.test(p) || /^[\\/]{2}[^\\/]/.test(p);
+}
+/**
+ * Read the plan and check every row: `file` must be a *.cspeach.json file
+ * directly in one of the old save locations; `target` must be null or an
+ * existing folder given as a full path, never in or under CSPeach's own
+ * folder. Bad rows are reported and dropped (and counted).
+ */
+async function readCheckedPlan(planPath, sources, io) {
+    let raw;
+    try {
+        raw = JSON.parse(stripBom(await fs.readFile(planPath, 'utf8')));
+    }
+    catch {
+        io.log(`The plan file could not be read: ${planPath}`);
+        return null;
+    }
+    if (!Array.isArray(raw)) {
+        io.log(`The plan file is not a list of rows: ${planPath}`);
+        return null;
+    }
+    const srcKeys = new Set(sources.map(normDir));
+    const rows = [];
+    let refused = 0;
+    for (const r of raw) {
+        const file = r?.file;
+        if (typeof file !== 'string' || !isFullPath(file) || !ENVELOPE.test(file)
+            || !srcKeys.has(normDir(path.dirname(file))) || !(await isPlainFile(file))) {
+            io.log(`Skipped ${String(file)}: not in an earlier save location.`);
+            refused++;
+            continue;
+        }
+        const target = r?.target ?? null;
+        if (target !== null && (typeof target !== 'string' || !isFullPath(target) || !(await isFolder(target)))) {
+            io.log(`Skipped ${path.basename(file)}: ${String(target)} is not an existing full folder path.`);
+            refused++;
+            continue;
+        }
+        if (target !== null && insideCliHome(target)) {
+            io.log(`Skipped ${path.basename(file)}: ${target} would be inside CSPeach's own folder.`);
+            refused++;
+            continue;
+        }
+        rows.push({ file, target });
+    }
+    return { rows, refused };
+}
+/** Inside the CLI home only *.cspeach.json files directly in it may be read. */
+function allowedFromCliHome(p) {
+    const home = normDir(cspeachRoot());
+    const k = normDir(p);
+    if (k !== home && !k.startsWith(home + path.sep))
+        return true;
+    return normDir(path.dirname(p)) === home && ENVELOPE.test(p);
+}
+/** The lane file and spec-gap a plan links to, as copy jobs into `target`. */
+async function linkedJobs(planFile, env, target, io) {
+    const jobs = [];
+    const from = env?.artefactType === 'plan' ? env?.content?.from : undefined;
+    const find = async (rel) => {
+        for (const c of linkedFileCandidates(planFile, rel))
+            if (allowedFromCliHome(c) && (await isPlainFile(c)))
+                return c;
+        return null;
+    };
+    const lane = from?.lane?.path;
+    if (typeof lane === 'string') {
+        const rel = canonicalLanePath(lane);
+        const src = isLanePath(rel) ? await find(rel) : null;
+        if (src)
+            jobs.push({ src, dest: path.join(target, ...rel.split('/')) });
+        else
+            io.log(`${path.basename(planFile)}: its lane file was not found; the plan is copied without it.`);
+    }
+    const gap = from?.specGap?.path;
+    if (typeof gap === 'string') {
+        const src = ENVELOPE.test(gap) ? await find(gap) : null;
+        if (src)
+            jobs.push({ src, dest: path.join(target, '.cspeach', path.basename(src)) });
+        else
+            io.log(`${path.basename(planFile)}: its spec-gap file was not found; the plan is copied without it.`);
+    }
+    return jobs;
+}
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+/**
+ * Copy one chain's jobs. Checks first (never write over a different file),
+ * then copies with sha256 checks. On any failure, this run's new copies of
+ * the chain are removed again, so a chain is never left half copied.
+ */
+async function copyChain(jobs, names, io) {
+    const todo = [];
+    let same = 0;
+    try {
+        for (const j of jobs) {
+            if (normDir(j.src) === normDir(j.dest)) {
+                same++;
+                continue;
+            } // this file is already in the target
+            if (await isPlainFile(j.dest)) {
+                if ((await sha256(j.dest)) === (await sha256(j.src))) {
+                    same++;
+                    continue;
+                }
+                io.log(`Not copied: ${names}. ${j.dest} already exists with different content.`);
+                return { ok: false, copied: 0, same: 0 };
+            }
+            let taken = true;
+            try {
+                await fs.lstat(j.dest);
+            }
+            catch {
+                taken = false;
+            }
+            if (taken) {
+                io.log(`Not copied: ${names}. ${j.dest} already exists.`);
+                return { ok: false, copied: 0, same: 0 };
+            }
+            if (destInCliHome(j.dest)) {
+                io.log(`Not copied: ${names}. ${j.dest} would be inside CSPeach's own folder.`);
+                return { ok: false, copied: 0, same: 0 };
+            }
+            todo.push(j);
+        }
+    }
+    catch {
+        io.log(`Not copied: ${names}. A file could not be read.`);
+        return { ok: false, copied: 0, same: 0 };
+    }
+    const made = [];
+    for (const j of todo) {
+        try {
+            await fs.mkdir(path.dirname(j.dest), { recursive: true });
+            // Checked again now the folder exists (it may have changed since the check above).
+            if (destInCliHome(j.dest))
+                throw new Error('inside the CLI home');
+            await fs.copyFile(j.src, j.dest, fsc.COPYFILE_EXCL);
+            made.push(j.dest);
+            if ((await sha256(j.dest)) !== (await sha256(j.src)))
+                throw new Error('copy differs');
+        }
+        catch {
+            for (const d of made)
+                await fs.rm(d, { force: true }).catch(() => { });
+            io.log(`Not copied: ${names}. Copying ${path.basename(j.src)} failed, so this run's copies of these files were removed. The originals are untouched.`);
+            return { ok: false, copied: 0, same: 0 };
+        }
+    }
+    return { ok: true, copied: made.length, same };
+}
+async function apply(planPath, io) {
+    const sources = legacyDirsFor(io.cwd);
+    const plan = await readCheckedPlan(planPath, sources, io);
+    if (!plan)
+        return 1;
+    const byFile = new Map(plan.rows.map((r) => [normDir(r.file), r]));
+    // Chains are worked out again from the files themselves, not from the plan.
+    const files = await scanSources(sources);
+    let copied = 0;
+    let same = 0;
+    let notCopied = 0;
+    const touched = new Set();
+    for (const group of linkChains(files)) {
+        const members = group.map((i) => files[i]);
+        const planned = members.map((m) => byFile.get(normDir(m.path)));
+        const targets = planned.map((r) => r?.target ?? null);
+        if (targets.every((t) => t === null))
+            continue;
+        const names = members.map((m) => path.basename(m.path)).join(', ');
+        const target = targets.find((t) => t !== null);
+        if (planned.some((r) => !r) || targets.some((t) => t === null || normDir(t) !== normDir(target))) {
+            io.log(`Not copied: ${names}. They are linked and must go to one folder together.`);
+            notCopied += members.length;
+            continue;
+        }
+        // Every file of the chain, plus each plan's lane file and spec-gap.
+        const jobs = members.map((m) => ({ src: m.path, dest: path.join(target, '.cspeach', path.basename(m.path)) }));
+        for (const m of members)
+            jobs.push(...(await linkedJobs(m.path, m.env, target, io)));
+        const byDest = new Map();
+        let clash = false;
+        for (const j of jobs) {
+            const seen = byDest.get(normDir(j.dest));
+            if (!seen)
+                byDest.set(normDir(j.dest), j);
+            else if (normDir(seen.src) !== normDir(j.src))
+                clash = true;
+        }
+        if (clash) {
+            io.log(`Not copied: ${names}. Two files would get the same name in ${target}.`);
+            notCopied += members.length;
+            continue;
+        }
+        const r = await copyChain([...byDest.values()], names, io);
+        if (!r.ok) {
+            notCopied += members.length;
+            continue;
+        }
+        copied += r.copied;
+        same += r.same;
+        if (r.copied > 0)
+            touched.add(target);
+    }
+    for (const t of touched) {
+        try {
+            ensureProjectId(path.join(t, '.cspeach'));
+        }
+        catch {
+            io.log(`Could not write the project id in ${t}.`);
+        }
+    }
+    io.log(`Copied ${plural(copied, 'file')}${same ? `, ${same} already there` : ''}${notCopied ? `, ${notCopied} not copied` : ''}. Every copy was checked.`);
+    io.log('The originals are still in place.');
+    if (copied + same > 0)
+        io.log(`To delete the originals whose copies check out: cspeach files sort --clean ${planPath}`);
+    return plan.refused > 0 || notCopied > 0 ? 1 : 0;
+}
+/* ── clean ──────────────────────────────────────────────────────────────── */
+async function defaultConfirm(message) {
+    const { confirm } = await import('../repl/themed-prompts.js');
+    return confirm({ message, default: false });
+}
+/** The copy of `file` in `<target>/.cspeach`, when it matches by sha256. */
+async function checkedCopy(file, target) {
+    const copy = path.join(target, '.cspeach', path.basename(file));
+    if (normDir(copy) === normDir(file))
+        return null;
+    try {
+        if (!(await isPlainFile(copy)) || !(await isPlainFile(file)))
+            return null;
+        return (await sha256(copy)) === (await sha256(file)) ? copy : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function clean(planPath, io) {
+    const sources = legacyDirsFor(io.cwd);
+    const plan = await readCheckedPlan(planPath, sources, io);
+    if (!plan)
+        return 1;
+    const byFile = new Map(plan.rows.map((r) => [normDir(r.file), r]));
+    const files = await scanSources(sources);
+    // A chain's originals go only when EVERY member's copy checks out.
+    let kept = 0;
+    const ready = [];
+    for (const group of linkChains(files)) {
+        const members = group.map((i) => files[i]);
+        if (members.every((m) => !byFile.get(normDir(m.path))?.target))
+            continue;
+        const pairs = [];
+        for (const m of members) {
+            const t = byFile.get(normDir(m.path))?.target;
+            const copy = t ? await checkedCopy(m.path, t) : null;
+            if (!t || !copy)
+                break;
+            pairs.push({ file: m.path, target: t, copy });
+        }
+        if (pairs.length === members.length)
+            ready.push(...pairs);
+        else {
+            io.log(`Kept: ${members.map((m) => path.basename(m.path)).join(', ')}. Not every linked file has a checked copy.`);
+            kept += members.length;
+        }
+    }
+    const status = () => (plan.refused > 0 || kept > 0 ? 1 : 0);
+    if (ready.length === 0) {
+        io.log('No originals with a checked copy. Run --apply first.');
+        return status();
+    }
+    io.log('These originals have a checked copy:');
+    for (const r of ready)
+        io.log(`  ${r.file}  ->  ${r.copy}`);
+    let yes = false;
+    try {
+        yes = await (io.confirm ?? defaultConfirm)(`Delete these ${ready.length} originals? The copies stay.`);
+    }
+    catch {
+        yes = false;
+    }
+    if (!yes) {
+        io.log('Nothing deleted.');
+        return status();
+    }
+    let deleted = 0;
+    for (const r of ready) {
+        // Check again right before deleting.
+        try {
+            if ((await checkedCopy(r.file, r.target)) !== null) {
+                await fs.unlink(r.file);
+                deleted++;
+                continue;
+            }
+            io.log(`Kept ${r.file}: its copy no longer matches.`);
+        }
+        catch {
+            io.log(`Kept ${r.file}: it could not be deleted.`);
+        }
+        kept++;
+    }
+    io.log(`Deleted ${plural(deleted, 'original')}.`);
+    return status();
+}