@zenera/cli 1.1.22 → 1.1.24

package/dist/commands/export.js

@@ -0,0 +1,255 @@
+import { lockHolder, memoryDir, readProjectConfig } from '@zenera/neo';
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { ARCHIVE_FORMAT, collect, ENV_EXAMPLE, envExample, MANIFEST_FILE, safeName, writeArchive, } from "../archive.js";
+import { one, parse } from "../args.js";
+import { ENV_FILE } from "../env.js";
+import { stamp } from "../ids.js";
+import { isBusy, Registry, sessionIds, sessionsDir } from "../projects.js";
+import { project as resolveProject } from "../resolve.js";
+import { ownVersion } from "../scaffold.js";
+import { bold, count, cyan, dim, green, bytes as human, invalidError, json, note, progress, table, usageError, warn, writeAll, } from "../term.js";
+import { validateProject } from "../validate.js";
+const USAGE = 'zen export [project] [--out <file>] [--no-vectors] [--no-memory] [--force]';
+// ---------------------------------------------------------------------------
+// zen export
+//
+// A project is a directory, and the reason this is not `zip -r` is that half
+// of the directory is this machine rather than the project: the sessions, the
+// scratch, the `.env`. What is left is the thing somebody else can run, and
+// this writes exactly that — plus a manifest saying what it is, so `zen
+// import` can register it under the right name and tell the reader what is
+// still missing.
+//
+// The vectors travel by default, and that is the decision this command is
+// built around. Memory has no other source: a graph without its vectors
+// recalls by term overlap until every node is written again, and a rag index
+// without its `lance/` tree looks built and cannot search. `--no-vectors`
+// makes a small archive for someone who will run the restore step; the default
+// makes one that works when it is opened.
+//
+// What never travels, behind no flag: the values in `.env`. The names do, as
+// `.env.example`, because "which credentials does this need" is the first
+// question on the other end and the answer is not a secret.
+// ---------------------------------------------------------------------------
+export const pack = {
+    summary: 'Write a project to a shareable zip archive.',
+    usage: USAGE,
+    banner: { head: 'Zenera', accent: 'Export', subtitle: 'Project Archive', hue: 'emerald' },
+    details: [
+        'Carries agents.yaml, the agents/ tree, the specification and its',
+        'feedback, assets, memory, the sandbox and scripts, and the editor',
+        'files — everything that is the project.',
+        '',
+        'Leaves behind what belongs to this machine: sessions/, .tmp/, .git/,',
+        'node_modules/, lock files, any *.zip at the top of the project, and',
+        `.env. The names in .env become a ${ENV_EXAMPLE} with no values, so the`,
+        'other end knows what to fill in.',
+        '',
+        'Vectors travel by default — memory has no other source, and a rag',
+        'index without its lance/ tree looks built and cannot search.',
+        '--no-vectors leaves both out for a much smaller archive that needs',
+        '`zen rag <subject> restore` on arrival. --no-memory drops memory/',
+        'entirely, for an archive that shares the project and not what the',
+        'agents learned.',
+        '',
+        'The default name is <project>-<stamp>.zip in the current directory, so',
+        'two exports never overwrite one another. --out takes any path.',
+        '',
+        'A project that fails `zen check` is still exported, with a warning:',
+        'sending someone a broken project to ask for help is the point.',
+        'A memory held by a live run is refused — half a graph is not an',
+        'archive — and --force overrides that.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, {
+            out: { type: 'string' },
+            'no-vectors': { type: 'boolean' },
+            'no-memory': { type: 'boolean' },
+            force: { type: 'boolean' },
+        }, USAGE);
+        const found = await resolveProject({
+            cwd: ctx.cwd,
+            project: one(positionals, 'project', USAGE),
+        });
+        const dir = found.dir;
+        const force = values.force === true;
+        const vectors = values['no-vectors'] !== true;
+        const memory = values['no-memory'] !== true;
+        settled(dir, force, memory);
+        const out = destination(ctx.cwd, found.name, values.out, force);
+        const collected = collect(dir, { vectors, memory });
+        const extra = new Map();
+        const env = join(dir, ENV_FILE);
+        if (existsSync(env)) {
+            extra.set(ENV_EXAMPLE, envExample(readFileSync(env, 'utf8')));
+        }
+        const healthy = await sound(dir, found.name, ctx.json);
+        const manifest = {
+            format: ARCHIVE_FORMAT,
+            name: found.name,
+            root: safeName(found.name) ?? 'project',
+            exportedAt: new Date().toISOString(),
+            cli: ownVersion(),
+            vectors,
+            memory,
+            files: collected.files.length + extra.size,
+            bytes: collected.bytes,
+        };
+        const bar = ctx.json ? undefined : progress();
+        let done = 0;
+        const size = await writeArchive({
+            out,
+            root: manifest.root,
+            entries: collected.files,
+            extra,
+            manifest,
+            onFile: (rel) => {
+                done += 1;
+                bar?.update(`packing ${done}/${collected.files.length} ${dim(rel)}`);
+            },
+        });
+        bar?.done();
+        if (ctx.json) {
+            json({
+                file: out,
+                bytes: size,
+                files: manifest.files,
+                project: found.name,
+                root: manifest.root,
+                vectors,
+                memory,
+                skipped: collected.skipped,
+                ok: healthy,
+            });
+            return;
+        }
+        report(out, size, collected, extra.size, vectors, memory);
+    },
+};
+// ---------------------------------------------------------------------------
+// Refusing at the right moment
+// ---------------------------------------------------------------------------
+/**
+ * Nothing may be written while something is writing to it.
+ *
+ * Memory is the hard case: the store is a graph, a manifest and a vector file
+ * that only mean anything together, and a copy taken mid-write is an archive
+ * that opens and is wrong — which is worse than one that does not open. A run
+ * holding a session is milder; the session is not in the archive at all, and
+ * the only thing it can disturb is an asset the agent is editing.
+ */
+function settled(dir, force, memory) {
+    const at = memory ? memoryAt(dir) : undefined;
+    const held = at ? lockHolder(at) : undefined;
+    if (held && !force) {
+        throw invalidError(`this project's memory is in use (pid ${held.pid}, since ${held.startedAt})`, 'wait for that run to finish, or: zen export --no-memory');
+    }
+    const busy = sessionIds(dir).filter((id) => isBusy(join(sessionsDir(dir), id)));
+    if (busy.length > 0 && !force) {
+        warn(`${count(busy.length, 'session')} still running — the archive is a snapshot`);
+    }
+}
+/**
+ * The configured memory directory, or nothing when the project will not load —
+ * which is a project this command exports anyway, so it cannot be an error here.
+ */
+function memoryAt(dir) {
+    try {
+        return memoryDir(dir, readProjectConfig(dir).config);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether the project is sound — asked, reported, and never obeyed.
+ *
+ * Exporting a project that does not load is a legitimate thing to want: it is
+ * how you send it to somebody who can tell you why. So this warns and returns,
+ * and the archive is written either way. Nothing is built and no model is
+ * asked; this is a reading of files and costs nothing.
+ */
+async function sound(dir, name, quiet) {
+    const registered = (await Registry.open()).findPath(dir) !== undefined;
+    const report = await validateProject({
+        dir,
+        name,
+        registered,
+        sandbox: { enabled: false },
+        models: { enabled: false },
+    });
+    if (!report.ok && !quiet) {
+        warn(`this project has ${count(report.counts.errors, 'error')} — ` +
+            `exporting it anyway (see: zen check)`);
+    }
+    return report.ok;
+}
+/**
+ * Where the archive goes. The stamp is in the default name because an export
+ * is a point in time, and because two of them in one afternoon should be two
+ * files rather than one silently replaced.
+ */
+function destination(cwd, name, out, force) {
+    const at = out
+        ? resolve(isAbsolute(out) ? out : join(cwd, out))
+        : join(cwd, `${slug(name)}-${stamp()}.zip`);
+    if (existsSync(at) && !force) {
+        throw usageError(`${at} already exists`, 'overwrite it with --force, or name another --out');
+    }
+    return at;
+}
+/** A project name as a file name: what a shell and a browser both accept. */
+function slug(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+/, '');
+    return cleaned.length > 0 ? cleaned : 'project';
+}
+// ---------------------------------------------------------------------------
+// The report
+// ---------------------------------------------------------------------------
+/** What the skip reasons are called when somebody reads them. */
+const SKIPPED = {
+    sessions: 'session directories',
+    scratch: '.tmp/',
+    git: 'git history',
+    modules: 'node_modules/',
+    env: `${ENV_FILE} (replaced by ${ENV_EXAMPLE})`,
+    locks: 'lock files',
+    noise: 'editor noise',
+    archives: 'zip archives beside the project',
+    vectors: 'vector stores (--no-vectors)',
+    memory: 'memory/ (--no-memory)',
+    links: 'symbolic links',
+};
+function report(out, size, collected, extra, vectors, memory) {
+    const groups = new Map();
+    for (const file of collected.files) {
+        const at = file.rel.indexOf('/');
+        const key = at < 0 ? '(root)' : `${file.rel.slice(0, at)}/`;
+        const group = groups.get(key) ?? { files: 0, bytes: 0 };
+        group.files += 1;
+        group.bytes += file.bytes;
+        groups.set(key, group);
+    }
+    const rows = [...groups.entries()]
+        .sort((a, b) => b[1].bytes - a[1].bytes)
+        .map(([key, g]) => [cyan(key), count(g.files, 'file'), dim(human(g.bytes))]);
+    writeAll(table(rows));
+    note();
+    note(`${green('wrote')} ${bold(out)} ${dim(human(size))}`);
+    note(dim(`${count(collected.files.length + extra, 'file')} inside, ` +
+        `described by ${MANIFEST_FILE}`));
+    for (const [reason, n] of Object.entries(collected.skipped)) {
+        note(dim(`  left out ${count(n, 'path')}: ${SKIPPED[reason] ?? reason}`));
+    }
+    if (!vectors) {
+        note(dim('  no vectors: the other end needs `zen rag <subject> restore`, ' +
+            'and memory will recall by term overlap'));
+    }
+    if (!memory) {
+        note(dim('  no memory: the project travels, what the agents learned does not'));
+    }
+    note();
+    note(`open it with ${bold('zen import')} ${dim(out)}`);
+}
+//# sourceMappingURL=export.js.map

package/dist/commands/import.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../command.ts';
+export declare const unpack: Command;
+//# sourceMappingURL=import.d.ts.map

package/dist/commands/import.js

@@ -0,0 +1,173 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { ENV_EXAMPLE, extractArchive, readManifest, safeName, } from "../archive.js";
+import { parse } from "../args.js";
+import { ENV_FILE } from "../env.js";
+import { isProjectDir, Registry } from "../projects.js";
+import { bold, count, cyan, dim, green, bytes as human, invalidError, json, note, progress, usageError, warn, } from "../term.js";
+const USAGE = 'zen import <file.zip> [dir] [--name <name>] [--force] [--no-register]';
+// ---------------------------------------------------------------------------
+// zen import
+//
+// The other half of `zen export`, and the half that has to be suspicious. An
+// archive is a file somebody sent, and everything in it is a claim: the paths
+// it says to write, the sizes it says they unpack to, the modes it says they
+// carry. The checks for all three live in archive.ts, next to the code that
+// writes them, because a guard that lives apart from the thing it guards is a
+// guard that drifts.
+//
+// The rule this command is built on: nothing in the archive is executed. It
+// carries a `scripts/` tree, a Dockerfile and a `.github/` tree, and every one
+// of those is something a machine could be talked into running on arrival.
+// So this writes files, registers a name, and prints the commands you would
+// type next — which you can read first, because they are on your screen and
+// not in somebody else's zip.
+// ---------------------------------------------------------------------------
+export const unpack = {
+    summary: 'Unpack a project archive written by zen export.',
+    usage: USAGE,
+    banner: { head: 'Zenera', accent: 'Import', subtitle: 'Project Archive', hue: 'violet' },
+    details: [
+        'Unpacks into ./<project> unless a directory is named. A directory',
+        'that already has something in it is refused; --force writes over it.',
+        '',
+        'The project is registered under the name in the archive, so `zen list`',
+        'and `zen open` find it straight away. --name registers it under a',
+        'different one, which is also what to use when that name is taken.',
+        '--no-register unpacks and leaves the registry alone.',
+        '',
+        `Credentials are not in the archive. ${ENV_EXAMPLE} names what the`,
+        `project needs: copy it to ${ENV_FILE} and fill it in.`,
+        '',
+        'Nothing in the archive is run — not the setup script, not the',
+        'Dockerfile, not a single line of the .github/ tree. The commands to',
+        'run next are printed for you to read and type.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, {
+            name: { type: 'string' },
+            force: { type: 'boolean' },
+            'no-register': { type: 'boolean' },
+        }, USAGE);
+        if (positionals.length === 0) {
+            throw usageError('no archive named', USAGE);
+        }
+        if (positionals.length > 2) {
+            throw usageError(`expected an archive and a directory, got ${positionals.length}`, USAGE);
+        }
+        const file = at(ctx.cwd, positionals[0]);
+        if (!existsSync(file)) {
+            throw usageError(`no such file: ${file}`);
+        }
+        const manifest = await readManifest(file);
+        const name = named(values.name, manifest);
+        const into = positionals[1] ? at(ctx.cwd, positionals[1]) : join(ctx.cwd, name);
+        empty(into, values.force === true);
+        const bar = ctx.json ? undefined : progress();
+        let done = 0;
+        const taken = await extractArchive({
+            file,
+            into,
+            root: manifest.root,
+            onFile: (rel) => {
+                done += 1;
+                bar?.update(`unpacking ${done}/${manifest.files} ${dim(rel)}`);
+            },
+        });
+        bar?.done();
+        if (!isProjectDir(into)) {
+            warn(`${into} has no agents.yaml — the archive did not hold a whole project`);
+        }
+        const registered = values['no-register'] !== true && (await register(name, into, ctx.json));
+        if (ctx.json) {
+            json({
+                dir: into,
+                name,
+                files: taken.files,
+                bytes: taken.bytes,
+                registered,
+                from: {
+                    project: manifest.name,
+                    exportedAt: manifest.exportedAt,
+                    cli: manifest.cli,
+                },
+                vectors: manifest.vectors,
+                memory: manifest.memory,
+            });
+            return;
+        }
+        report(name, into, taken.files, taken.bytes, registered, manifest);
+    },
+};
+// ---------------------------------------------------------------------------
+// Where it lands
+// ---------------------------------------------------------------------------
+const at = (cwd, path) => resolve(isAbsolute(path) ? path : join(cwd, path));
+/**
+ * The name it is registered under. `--name` wins, because the archive's own
+ * may already belong to something on this machine — and because it arrived
+ * from elsewhere, it is checked before it becomes a directory or a key.
+ */
+function named(wanted, manifest) {
+    const name = safeName(wanted ?? manifest.name);
+    if (!name) {
+        throw usageError(`"${wanted}" is not a usable project name`, USAGE);
+    }
+    return name;
+}
+/**
+ * A target with files in it is refused rather than merged. Unpacking over a
+ * project leaves a tree that is neither archive nor original — every file the
+ * archive holds replaced, every file it does not still there — and there is no
+ * reading of that which is useful. `--force` is the way to say you meant it.
+ */
+function empty(into, force) {
+    if (!existsSync(into)) {
+        return;
+    }
+    const held = readdirSync(into).filter((entry) => entry !== '.DS_Store');
+    if (held.length === 0 || force) {
+        return;
+    }
+    throw invalidError(`${into} is not empty`, 'name another directory, or overwrite what is there with --force');
+}
+/** Registration is a convenience; a name already taken is not a failed import. */
+async function register(name, dir, quiet) {
+    try {
+        const registry = await Registry.open();
+        registry.add(name, dir);
+        registry.save();
+        return true;
+    }
+    catch (err) {
+        if (!quiet) {
+            warn(`${err.message} — the project is on disk, ` +
+                `register it with: zen init ${dir} --name <other>`);
+        }
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// What to do next
+// ---------------------------------------------------------------------------
+function report(name, into, files, size, registered, manifest) {
+    note(`${green('unpacked')} ${bold(name)} ${dim(into)}`);
+    note(dim(`${count(files, 'file')}, ${human(size)}, exported by zen ${manifest.cli}`));
+    if (!registered) {
+        note(dim('not registered — reach it by path'));
+    }
+    note();
+    note(bold('next'));
+    if (existsSync(join(into, ENV_EXAMPLE))) {
+        note(`  ${cyan(`cp ${ENV_EXAMPLE} ${ENV_FILE}`)} ${dim('and fill in the credentials')}`);
+    }
+    if (!manifest.vectors) {
+        note(`  ${cyan('zen rag <subject> restore')} ` +
+            dim('— the vectors did not travel, and nothing searches until they are back'));
+    }
+    note(`  ${cyan(`zen check ${name}`)} ${dim('— what this machine is still missing')}`);
+    note(`  ${cyan(`zen open ${name}`)}`);
+    note();
+    note(dim('nothing in the archive has been run. scripts/ and .github/ are worth a read.'));
+}
+//# sourceMappingURL=import.js.map

package/dist/commands/index.d.ts

@@ -3,7 +3,11 @@ import type { Command } from '../command.ts';
 /**
  * Insertion order is the order help prints in, and it is deliberate: the four
  * a new user needs first, then the credentials-and-models pair, then the two
- * reports on a project, then the two that are only ever run on purpose.
+ * reports on a project, then the pair that moves a project between machines,
+ * then the ones that are only ever run on purpose.
+ *
+ * `export` and `import` are reserved words, so the two commands are declared
+ * under names a module can export and given their real ones here.
  */
 export declare const COMMANDS: Record<string, Command>;
 /** Names that are not listed in help but still work. */

package/dist/commands/index.js

@@ -1,5 +1,7 @@
 import { cache } from "./cache.js";
 import { check } from "./check.js";
+import { pack } from "./export.js";
+import { unpack } from "./import.js";
 import { init } from "./init.js";
 import { inspect } from "./inspect.js";
 import { key } from "./key.js";
@@ -14,7 +16,11 @@ import { version } from "./version.js";
 /**
  * Insertion order is the order help prints in, and it is deliberate: the four
  * a new user needs first, then the credentials-and-models pair, then the two
- * reports on a project, then the two that are only ever run on purpose.
+ * reports on a project, then the pair that moves a project between machines,
+ * then the ones that are only ever run on purpose.
+ *
+ * `export` and `import` are reserved words, so the two commands are declared
+ * under names a module can export and given their real ones here.
  */
 export const COMMANDS = {
     init,
@@ -26,6 +32,8 @@ export const COMMANDS = {
     models,
     check,
     inspect,
+    export: pack,
+    import: unpack,
     memory,
     sandbox,
     cache,
@@ -45,6 +53,10 @@ export const ALIASES = {
     edit: 'open',
     code: 'open',
     mock: 'faker',
+    pack: 'export',
+    archive: 'export',
+    unpack: 'import',
+    share: 'export',
 };
 export const EXTERNAL = {
     faker: {

package/dist/commands/inspect.d.ts

@@ -1,3 +1,14 @@
 import type { Command } from '../command.ts';
+import { type NodeDetail } from '../trace.ts';
 export declare const inspect: Command;
+/**
+ * Which parts print in full: everything `--part` names, or everything but
+ * `request`. A prefix matches, so `--part call` catches `call run_command (…)`.
+ */
+export declare function wholeParts(found: readonly NodeDetail[], values: {
+    part?: string[];
+    full?: boolean;
+}): (name: string) => boolean;
+/** One node, framed so a payload cannot be mistaken for the next node. */
+export declare function renderNode(node: NodeDetail, whole?: (name: string) => boolean): string;
 //# sourceMappingURL=inspect.d.ts.map