@astryxdesign/cli 0.6.4 → 0.6.5-canary.00f1ed9

package/api/hook/hook.doc.mjs

@@ -34,6 +34,7 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory to resolve @astryxdesign/core from.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.list',
@@ -43,7 +44,8 @@ export const doc = {
     {
       name: 'options.category',
       type: 'string',
-      description: 'List only hooks in this category.',
+      description:
+        "List only the hooks in this category, a key of the unfiltered list such as 'Media' or 'Focus'.",
     },
     {
       name: 'options.params',
@@ -54,7 +56,8 @@ export const doc = {
       name: 'options.detail',
       type: "'full' | 'compact' | 'brief'",
       description: 'Detail level for list views.',
-      default: "'full' for a named hook, 'brief' for list views",
+      default:
+        "'full' for a named hook; 'brief' for lists (returned as data.detail: 'names')",
     },
     {
       name: 'options.lang',
@@ -104,7 +107,7 @@ export const doc = {
     },
     {
       label: 'Browse a category',
-      code: "await hook(undefined, {category: 'State', detail: 'compact'});",
+      code: "await hook(undefined, {category: 'Media', detail: 'compact'});",
     },
   ],
   command: 'hook',

package/api/index.d.mts

@@ -18,6 +18,7 @@ export { integrationAddTheme } from "./integration/add-theme.mjs";
 export { integrationPackCheck } from "./integration/pack-check.mjs";
 export { AstryxError } from "./error.mjs";
 export { logger } from "./logger.mjs";
+export * from "../foundation/response/batch.type.mjs";
 export * from "./component/component.type.mjs";
 export * from "./docs/docs.type.mjs";
 export * from "./blog/blog.type.mjs";

package/api/index.mjs

@@ -3,7 +3,7 @@
 /**
  * @file Programmatic API for the Astryx CLI.
  *
- * Every function returns the same { type, data } envelope that `xds --json` outputs.
+ * Every function returns the same { type, data } envelope that `astryx --json` outputs.
  * Errors throw AstryxError (with optional .suggestions).
  *
  * @example
@@ -73,10 +73,12 @@ export {logger} from './logger.mjs';
  * @typedef {import('./logger.mjs').Logger} Logger
  */
 
-// ── Types (re-exported from each command's colocated `.type.mjs`) ─────
+// ── Types (re-exported from the shared response foundation and each command's
+// colocated `.type.mjs`) ──────────────────────────────────────────────────
 // Runtime no-ops (the .type.mjs files are `export {}`); tsc carries these
 // through to the generated api/index.d.mts so the public type surface exposes
-// every command's Options + response types by name.
+// the shared receipt vocabulary and every command's Options + response types.
+export * from '../foundation/response/batch.type.mjs';
 export * from './component/component.type.mjs';
 export * from './docs/docs.type.mjs';
 export * from './blog/blog.type.mjs';

package/api/init/init.doc.mjs

@@ -19,10 +19,9 @@ export const doc = {
     'Sets a project up with NO prompts, so it behaves identically for humans, ' +
     'agents, CI, and piped I/O. By default it installs the AGENTS.md/CLAUDE.md ' +
     'agent-docs cheat sheet, including guidance from configured integrations, and ' +
-    'prints getting-started guidance; `features` / ' +
-    '`all` add theme and page-building guidance and can scaffold a starter ' +
-    'template. With `removeAgents` it removes the managed agent-docs block ' +
-    'instead of installing.',
+    "prints getting-started guidance; `features` / `all` print only the chosen features' " +
+    'guidance instead (the theme feature also writes the annotated theme template). ' +
+    'With `removeAgents` it removes the managed agent-docs block instead of installing.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'init(options?: InitOptions, ctx?: {cwd?: string}): Promise<InitRunResponse | InitRemoveResponse>',
@@ -32,7 +31,7 @@ export const doc = {
       name: 'options.features',
       type: 'string',
       description:
-        'Comma-separated features to install: agents (agent docs), theme (writes the annotated theme.template.ts), template (page-template guidance).',
+        'Comma-separated features to install: agents (agent docs), theme (writes the annotated theme.template.ts), template (the page-building commands; writes a page only with templateName).',
     },
     {
       name: 'options.all',
@@ -47,7 +46,8 @@ export const doc = {
     {
       name: 'options.agent',
       type: 'string',
-      description: 'Agent preset: claude, cursor, codex, hermes, muse, all.',
+      description:
+        'Agent preset: claude, cursor, codex, hermes, muse, all. Used only when the agents feature runs.',
     },
     {
       name: 'options.agentDocsPath',
@@ -58,9 +58,14 @@ export const doc = {
       name: 'options.templateName',
       type: 'string',
       description:
-        'Scaffold a named page template (programmatic only; the CLI never sets it).',
+        'Scaffold this page template to src/pages/<name>/page.tsx. Used only when the template feature runs (features includes template, or all); otherwise ignored. Programmatic only; the CLI never sets it.',
+    },
+    {
+      name: 'ctx.cwd',
+      type: 'string',
+      description: 'Directory to set up.',
+      default: 'process.cwd()',
     },
-    {name: 'ctx.cwd', type: 'string', description: 'Directory to set up.'},
   ],
   returns: [
     {
@@ -71,13 +76,13 @@ export const doc = {
     {
       type: 'init.remove',
       description:
-        'Confirmation that the managed agent-docs block was removed (`data.removed: true`), returned when `removeAgents` is set.',
+        'Returned when `removeAgents` is set. `data.removed` is always true, even when no managed block was found.',
     },
   ],
   throws: [
     {
       code: 'ERR_UNKNOWN_AGENT',
-      when: '`agent` is not one of claude, cursor, codex, hermes, muse, all',
+      when: 'the agents feature runs (default mode, features includes agents, or all) and `agent` is not one of claude, cursor, codex, hermes, muse, all',
     },
     {
       code: 'ERR_UNKNOWN_FEATURE',
@@ -85,7 +90,7 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_TEMPLATE',
-      when: '`templateName` matches no bundled template',
+      when: 'the template feature runs and `templateName` matches no bundled template',
     },
     {
       code: 'ERR_FILE_EXISTS',
@@ -93,7 +98,7 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the template output path resolves outside cwd, for example through a symlinked src directory',
+      when: 'the template output path resolves outside cwd (for example through a symlinked src directory), or, with removeAgents, a managed agent-docs file resolves outside cwd through a symlink',
     },
   ],
   examples: [

package/api/integration/add-contribution.d.mts

@@ -31,7 +31,7 @@ export function integrationAddAgentDoc(line: string, options?: import("./integra
  *
  * @param {'component'|'doc'|'template'|'codemod'|'agent-doc'|'theme'} kind
  * @param {string} name
- * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string, parent?: string}} [options]
+ * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string, parent?: string, from?: string}} [options]
  * @returns {Promise<import('./integration-authoring.type.mjs').IntegrationAddResponse>}
  */
 export function integrationAdd(kind: "component" | "doc" | "template" | "codemod" | "agent-doc" | "theme", name: string, options?: {
@@ -42,4 +42,5 @@ export function integrationAdd(kind: "component" | "doc" | "template" | "codemod
     replaces?: string;
     extends?: string;
     parent?: string;
+    from?: string;
 }): Promise<import("./integration-authoring.type.mjs").IntegrationAddResponse>;

package/api/integration/add-contribution.mjs

@@ -1211,7 +1211,7 @@ const KIND_OPTIONS = {
   template: new Set(['cwd', 'dryRun', 'templateType']),
   codemod: new Set(['cwd', 'dryRun', 'to']),
   'agent-doc': new Set(['cwd', 'dryRun']),
-  theme: new Set(['cwd', 'dryRun']),
+  theme: new Set(['cwd', 'dryRun', 'from']),
 };
 
 /**
@@ -1238,7 +1238,7 @@ function validateKindOptions(kind, options) {
  *
  * @param {'component'|'doc'|'template'|'codemod'|'agent-doc'|'theme'} kind
  * @param {string} name
- * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string, parent?: string}} [options]
+ * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string, parent?: string, from?: string}} [options]
  * @returns {Promise<import('./integration-authoring.type.mjs').IntegrationAddResponse>}
  */
 export async function integrationAdd(kind, name, options = {}) {
@@ -1270,6 +1270,10 @@ export async function integrationAdd(kind, name, options = {}) {
     case 'agent-doc':
       return integrationAddAgentDoc(name, options);
     case 'theme':
-      return integrationAddTheme(name, options);
+      return integrationAddTheme(name, {
+        cwd: options.cwd,
+        dryRun: options.dryRun,
+        from: options.from,
+      });
   }
 }

package/api/integration/add-contribution.test.mjs

@@ -12,7 +12,7 @@ import {
   integrationAddTemplate,
 } from './add-contribution.mjs';
 import {validateLocalIntegration} from './validate-integration.mjs';
-import {DOCS_TREE_CLI} from '../../foundation/integrations/cli-requirement.mjs';
+import {NAMESPACE_DOCS_CLI} from '../../foundation/integrations/cli-requirement.mjs';
 
 let tmpDir;
 
@@ -355,7 +355,7 @@ describe('integrationAdd doc', () => {
 
     // The namespace doc needs a CLI that reads it, declared as an optional peer.
     const pkg = JSON.parse(fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'));
-    expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': `>=${DOCS_TREE_CLI}`});
+    expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': '>=0.6.4'});
     expect(pkg.peerDependenciesMeta).toEqual({'@astryxdesign/cli': {optional: true}});
 
     const second = await integrationAdd('doc', 'upgrading', {
@@ -429,7 +429,7 @@ describe('integrationAdd doc', () => {
     write('^0.6.0');
     await integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'acme'});
     expect(JSON.parse(fs.readFileSync(file, 'utf-8')).peerDependencies).toEqual({
-      '@astryxdesign/cli': `>=${DOCS_TREE_CLI}`,
+      '@astryxdesign/cli': `>=${NAMESPACE_DOCS_CLI}`,
     });
     write('^9.1.0');
     await integrationAdd('doc', 'upgrading', {cwd: tmpDir, parent: 'acme'});

package/api/integration/add-helpers.d.mts

@@ -8,7 +8,7 @@ export function findPackageDir(startDir: string): string;
 /**
  * @typedef {object} WritePlan
  * @property {string} path
- * @property {string} contents
+ * @property {string | Buffer} contents a Buffer is written byte for byte
  * @property {boolean} createOnly
  * @property {Buffer} [expectedOriginal] bytes captured before validation;
  *   a different current file is a concurrent edit and must never be overwritten
@@ -56,7 +56,10 @@ export function packageJsonUpdate(packageFile: string, rootPath: string, manifes
 export function applyWrites(plans: WritePlan[]): () => void;
 export type WritePlan = {
     path: string;
-    contents: string;
+    /**
+     * a Buffer is written byte for byte
+     */
+    contents: string | Buffer;
     createOnly: boolean;
     /**
      * bytes captured before validation;

package/api/integration/add-helpers.mjs

@@ -5,7 +5,8 @@
  *
  * Hosts the atomic staged-write transaction, package.json files-array
  * maintenance, package-dir resolution, and project-path normalization that
- * every `integration add <kind>` command needs. Stateless and side-effect-free
+ * every `integration add <kind>` command needs. `theme add` and `theme build`
+ * write through the same transaction. Stateless and side-effect-free
  * outside of {@link applyWrites}.
  */
 
@@ -40,7 +41,7 @@ export function findPackageDir(startDir) {
 /**
  * @typedef {object} WritePlan
  * @property {string} path
- * @property {string} contents
+ * @property {string | Buffer} contents a Buffer is written byte for byte
  * @property {boolean} createOnly
  * @property {Buffer} [expectedOriginal] bytes captured before validation;
  *   a different current file is a concurrent edit and must never be overwritten
@@ -192,21 +193,29 @@ export function packageJsonUpdate(
 
 // ── Atomic staged-write transaction ─────────────────────────────────
 
-/** @param {string} file */
+/**
+ * @param {string} file
+ * @returns {boolean} false when the file is still there
+ */
 function removeTemporary(file) {
   try {
     fs.rmSync(file, {force: true});
+    return true;
   } catch {
     // Best effort. The transaction error remains the actionable failure.
+    return false;
   }
 }
 
 /**
  * Restore writes that already published.  Best-effort so callers preserve
- * the original actionable error.
+ * the original actionable error; returns every path it could not put back.
  * @param {Array<WritePlan & {temporary: string, original: Buffer|null, mode: number}>} published
+ * @returns {string[]}
  */
 function rollbackWrites(published) {
+  /** @type {string[]} */
+  const unrestored = [];
   for (const plan of [...published].reverse()) {
     let restore = null;
     try {
@@ -225,12 +234,18 @@ function rollbackWrites(published) {
         fs.renameSync(restore, plan.path);
         restore = null;
       }
-    } catch {
-      // Best effort. A concurrent edit belongs to its writer, not this rollback.
+    } catch (error) {
+      // A created file that is already gone needs nothing. Any other failure
+      // leaves this call's bytes, or no bytes, where the original was.
+      const gone =
+        error instanceof Error &&
+        /** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT';
+      if (!(gone && plan.original == null)) unrestored.push(plan.path);
     } finally {
       if (restore != null) removeTemporary(restore);
     }
   }
+  return unrestored;
 }
 
 /** @param {string} file */
@@ -325,10 +340,22 @@ export function applyWrites(plans) {
       }
       published.push(plan);
     }
-    return () => rollbackWrites(published);
+    return () => {
+      rollbackWrites(published);
+    };
   } catch (error) {
-    for (const plan of staged) removeTemporary(plan.temporary);
-    rollbackWrites(published);
+    const leftovers = staged
+      .filter(plan => !removeTemporary(plan.temporary))
+      .map(plan => plan.temporary);
+    const unrestored = rollbackWrites(published);
+    if (error instanceof Error) {
+      if (unrestored.length > 0) {
+        error.message += ` Could not restore: ${unrestored.join(', ')}.`;
+      }
+      if (leftovers.length > 0) {
+        error.message += ` Could not remove temporary files: ${leftovers.join(', ')}.`;
+      }
+    }
     throw error;
   }
 }