@zenera/cli 1.1.14 → 1.1.16

package/dist/banner.d.ts

@@ -6,8 +6,12 @@ export interface BannerText {
     /** the line underneath, dim */
     subtitle: string;
 }
+export interface PrintBannerOptions {
+    /** Render the block face even when the terminal is narrower than it. */
+    readonly full?: boolean;
+}
 export declare const NEO_BANNER: BannerText;
 export declare function bannerLines(text: BannerText, columns?: number): string[];
 /** Narration, and only for someone watching. */
-export declare function printBanner(text: BannerText): void;
+export declare function printBanner(text: BannerText, options?: PrintBannerOptions): void;
 //# sourceMappingURL=banner.d.ts.map

package/dist/banner.js

@@ -112,12 +112,12 @@ export function bannerLines(text, columns = process.stderr.columns || 80) {
     return lines;
 }
 /** Narration, and only for someone watching. */
-export function printBanner(text) {
+export function printBanner(text, options = {}) {
     if (!process.stderr.isTTY) {
         return;
     }
     note('');
-    for (const line of bannerLines(text)) {
+    for (const line of bannerLines(text, options.full ? Infinity : undefined)) {
         note(line);
     }
     note('');

package/dist/command.d.ts

@@ -9,6 +9,11 @@ export interface Command {
     readonly usage: string;
     /** lines printed under the usage line by `zen help <command>` */
     readonly details?: readonly string[];
+    /**
+     * Answers `--help` itself, for a command whose arguments select a page the
+     * frame cannot see. Without it the frame prints this command's own page.
+     */
+    help?(ctx: Context): Promise<void> | void;
     run(ctx: Context): Promise<void>;
 }
 //# sourceMappingURL=command.d.ts.map

package/dist/commands/init.js

@@ -9,7 +9,7 @@ import { probeAll } from "../liveness.js";
 import { ensurePodmanReady } from "../podman.js";
 import { isProjectDir, Registry } from "../projects.js";
 import { scaffold } from "../scaffold.js";
-import { bold, cyan, dim, green, invalidError, json, note, progress, usageError, write, yellow, } from "../term.js";
+import { bold, cyan, dim, green, json, note, progress, usageError, write, yellow, } from "../term.js";
 const USAGE = 'zen init [dir] [--name <name>] [--model <ref>] [--force]';
 /**
  * The model each provider gets scaffolded with, when it is the one chosen.
@@ -101,6 +101,11 @@ export const init = {
         'find it by name. Editor files (.vscode/settings.json and the .github/',
         'tree) are written alongside, replacing any already there.',
         '',
+        'A directory that is already a project is adopted rather than rebuilt:',
+        'it is registered under its own name, and nothing in it is touched.',
+        'That is how a project someone else wrote becomes a name on this',
+        'machine after a clone.',
+        '',
         'SPECIFICATION.md states what the project is for and what it may do,',
         'and describes the one that was just written. Say what you are building',
         'there, then run /sync-with-spec in your editor to make the rest match.',
@@ -122,7 +127,8 @@ export const init = {
         const dir = resolve(ctx.cwd, one(positionals, 'directory', USAGE) ?? '.');
         const name = values.name ?? basename(dir);
         if (isProjectDir(dir)) {
-            throw invalidError(`${dir} is already a project`);
+            await adopt(dir, values, ctx.json);
+            return;
         }
         if (existsSync(dir) && readdirSync(dir).length > 0 && !values.force) {
             throw usageError(`${dir} is not empty`, 'pass --force to write into it anyway');
@@ -177,6 +183,44 @@ export const init = {
         write(dir);
     },
 };
+/**
+ * Takes a directory that is already a project into the registry.
+ *
+ * The registry lives in `$HOME`, so a project that arrives by clone, copy or
+ * `mv` is a working project that no name resolves to — and the only thing
+ * missing is the entry. Scaffolding over it would be the wrong repair: the
+ * files are somebody's work, and this writes none of them.
+ *
+ * Idempotent, because the honest answer to `zen init` in a project that is
+ * already listed is "it is", not an error.
+ */
+async function adopt(dir, values, quiet) {
+    ensureHome();
+    const registry = await Registry.open();
+    const listed = registry.findPath(dir);
+    const name = values.name ?? listed?.name ?? basename(dir);
+    const renamed = listed !== undefined && listed.name !== name;
+    registry.add(name, dir);
+    registry.save();
+    const sandbox = await prepareSandbox(dir, quiet);
+    if (quiet) {
+        json({ name, path: dir, adopted: true, listed: listed !== undefined, sandbox });
+        return;
+    }
+    const what = listed === undefined
+        ? green('registered')
+        : renamed
+            ? green('renamed')
+            : dim('already registered');
+    note(`${what} ${bold(name)} ${dim(dir)}`);
+    // Nothing here was scaffolded, so the flags that shape a scaffold did not apply.
+    if (values.model) {
+        note(`${yellow('--model ignored')} ${dim('— the model this project uses is in agents.yaml')}`);
+    }
+    note();
+    note(`Next: ${cyan(`cd ${dir}`)} then ${cyan('zen check')}`);
+    write(dir);
+}
 /**
  * Builds the sandbox image the project was just given, here rather than on the
  * first run.

package/dist/main.js

@@ -57,9 +57,11 @@ async function main(argv) {
     // Narration, so `--json` and every pipe are untouched by it. A command
     // living in another package brings its own brand, but only once it is
     // actually there — a banner over "not installed" is a claim about nothing.
-    if (!json) {
+    const ragSearch = name === 'rag' && ['docs', 'schema'].includes(rest[0]) && rest[1] === 'search';
+    const interactive = rest.includes('--interactive');
+    if (!json && (!ragSearch || interactive)) {
         const brand = external && hasExternal(external) ? external.banner : undefined;
-        printBanner(brand ?? NEO_BANNER);
+        printBanner(brand ?? NEO_BANNER, { full: ragSearch && interactive });
     }
     if (parts.name === 'help') {
         await usage(rest[0]);
@@ -73,15 +75,17 @@ async function main(argv) {
         fail(`unknown command "${parts.name}"`, `run ${bold(`${NAME} --help`)} for the list`);
         return EXIT.usage;
     }
-    if (values.help) {
-        await usage(name);
-        return EXIT.ok;
-    }
     // `-C` is consumed here so no command ever reads `process.cwd()` itself,
     // and every relative path in every command means the same thing.
     const cwd = resolve(values.directory ?? process.cwd());
     try {
         const one = command ?? (await loadExternal(name, external));
+        if (values.help) {
+            // A command that nests its own pages answers for them; the frame
+            // only knows the one page it printed the command's name on.
+            await (one.help ? one.help({ args: rest, json, cwd }) : usage(name));
+            return EXIT.ok;
+        }
         await one.run({ args: rest, json, cwd });
         return EXIT.ok;
     }

package/dist/validate.js

@@ -88,7 +88,7 @@ export async function validateProject(opts) {
             where: root,
             message: 'this directory is not registered, so `zen open` and `zen list` will not ' +
                 'find it by name (naming it by path, as now, works either way)',
-            fix: `register it: zen init ${root} --force`,
+            fix: `register it: zen init ${root}`,
         });
     }
     // -----------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.14",
+    "version": "1.1.16",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -51,7 +51,7 @@
         "@inkjs/ui": "^2.0.0",
         "ink": "^7.1.1",
         "react": "^19.2.8",
-        "@zenera/neo": "^1.1.14",
+        "@zenera/neo": "^1.1.16",
         "@anthropic-ai/sdk": "^0.120.0",
         "@google/genai": "^2.18.0",
         "@openrouter/sdk": "^1.2.80",