@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/clients/cli/commands/template.doc.mjs

@@ -13,14 +13,16 @@ export const doc = {
   type: 'command',
   name: 'template',
   displayName: 'astryx template',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Inject a page or block template',
   description:
     'One entry point for the template family: with no name it lists the discovered ' +
     'templates; with a name it shows the source or a layout skeleton, or scaffolds it ' +
-    'into the project at a target path. Narrow an ambiguous name with --type and/or --package. ' +
-    '--cdn writes the no-build-step CDN starter page, which ships as an asset rather than as ' +
-    'a discovered template.',
+    'into the project at a target path. A configured integration replacement is the ' +
+    'default for its Core id; use --package @astryxdesign/core for the original. ' +
+    'Narrow other ambiguous names with --type and/or --package. --cdn writes the ' +
+    'no-build-step CDN starter page, which ships as an asset rather than as a ' +
+    'discovered template.',
   fn: 'template',
   args: [
     {
@@ -55,7 +57,8 @@ export const doc = {
     {
       flag: '--package <pkg>',
       param: 'options.package',
-      description: 'Narrow to templates from a specific package',
+      description:
+        'Narrow to templates from a specific package. Use @astryxdesign/core to select an original hidden by an integration replacement.',
     },
     {
       flag: '--skeleton',
@@ -81,15 +84,29 @@ export const doc = {
   ],
   examples: [
     {label: 'List templates', cli: 'astryx template --json'},
+    {
+      label: 'List exact Core ids',
+      cli: 'astryx --json template --list --package @astryxdesign/core',
+    },
     {
       label: 'Scaffold into the app',
       cli: 'astryx template dashboard ./src/app',
     },
+    {
+      label: 'Select a replaced Core original',
+      cli: 'astryx template shell-side-nav ./src/app --package @astryxdesign/core',
+    },
     {label: 'CDN starter page', cli: 'astryx template --cdn'},
-    {label: 'CDN starter page, elsewhere', cli: 'astryx template --cdn public/demo.html'},
+    {
+      label: 'CDN starter page, elsewhere',
+      cli: 'astryx template --cdn public/demo.html',
+    },
   ],
   exitCodes: [
-    {code: 0, when: 'success, including a CDN page left untouched because it already exists'},
+    {
+      code: 0,
+      when: 'success, including a CDN page left untouched because it already exists',
+    },
     {
       code: 1,
       when: 'unknown or ambiguous template, no source, a path escape, or an existing target without --overwrite',

package/clients/cli/commands/template.mjs

@@ -4,12 +4,9 @@
  * @file template command — thin CLI wrapper around api/template.mjs
  */
 
-import * as path from 'node:path';
-import * as fs from 'node:fs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
 import {emit, section, text, records, code} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
-import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {template as templateApi} from '../../../api/template/template.mjs';
 import {Project} from '../../../foundation/config/project.mjs';
 import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
@@ -21,18 +18,6 @@ import {doc as templateFn} from '../../../api/template/template.doc.mjs';
 
 export {discoverTemplates, listTemplates} from '../../../api/template/template.mjs';
 
-/**
- * A template entry as produced by the discover* helpers in api/template.mjs.
- * The api layer returns these as `object[]`; this local shape captures the
- * fields the command consumes. Remove once api/template.mjs exports a precise
- * type for its discovered templates.
- * @typedef {object} DiscoveredTemplate
- * @property {'page' | 'block'} type
- * @property {string} dirName
- * @property {string} name
- * @property {string} filePath
- */
-
 /**
  * The discriminated response returned by the template API. The api layer
  * currently declares `{type: string, data: unknown}`; narrow it here to the
@@ -89,36 +74,11 @@ export function registerTemplate(program) {
       // doctor integration validate. Best-effort; suppressed in --json mode.
       try {
         const project = await Project.load(process.cwd());
-        await warnOnIntegrationIssues(
-          /** @type {Array<import('../../../foundation/integrations/integrations.mjs').LoadedIntegration>} */ (
-            project.loadedIntegrations
-          ),
-          {json},
-        );
+        await warnOnIntegrationIssues(project, {json});
       } catch {
         // Never let the nudge break the command.
       }
 
-      // Pre-flight overwrite check (only when we'd actually copy a file).
-      // The API resolves the destination; we need to mirror its logic
-      // narrowly enough to detect collisions before invoking it.
-      if (
-        name &&
-        targetPath &&
-        !options.list &&
-        !options.skeleton &&
-        !options.cdn
-      ) {
-        const collision = await detectTemplateCollision(name, targetPath);
-        if (collision && !options.overwrite) {
-          const rel = path.relative(process.cwd(), collision) || collision;
-          const msg =
-            `Refusing to overwrite existing file ${rel}. ` +
-            `Re-run with --overwrite (or -f) to replace it.`;
-          return cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
-        }
-      }
-
       /** @type {TemplateResponse} */
       let result;
       try {
@@ -156,12 +116,14 @@ export function registerTemplate(program) {
           // isn't the built-in core package.
           /** @param {import('../../../api/template/template.type.mjs').TemplateListEntry} t */
           const toRow = t => ({
+            id: t.id,
             name: t.isReady ? t.name : `${t.name} (WIP)`,
             description: t.description,
             package:
               t.package && t.package !== '@astryxdesign/core' ? t.package : '',
+            replaces: t.replaces ?? '',
           });
-          const fields = ['name', 'description', 'package'];
+          const fields = ['id', 'name', 'description', 'package', 'replaces'];
           emit(
             pages.length > 0 && section('Page Templates'),
             pages.length > 0 && records(pages.map(toRow), {fields}),
@@ -229,52 +191,3 @@ export function registerTemplate(program) {
     },
   });
 }
-
-/**
- * Mirror the destination-resolution logic in api/template.mjs so we can
- * detect a clobber before invoking the API.
- *
- * Returns the absolute destination file path if it already exists, or
- * `null` otherwise (template missing, no collision, or list/skeleton mode).
- *
- * Path-safety enforcement happens inside the API; here we only need
- * enough precision to check existence — a false negative just means the
- * API will catch the issue and abort.
- *
- * @param {string} name
- * @param {string} targetPath
- * @returns {Promise<string | null>}
- */
-async function detectTemplateCollision(name, targetPath) {
-  const {discoverTemplates} = await import('../../../api/template/template.mjs');
-  /** @type {DiscoveredTemplate[]} */
-  let templates;
-  try {
-    templates = /** @type {DiscoveredTemplate[]} */ (
-      await discoverTemplates(process.cwd())
-    );
-  } catch {
-    return null;
-  }
-  const match = templates.find(t => t.dirName === name);
-  if (!match) return null;
-
-  // Resolve target as the API will. We can't call assertWithin here
-  // because the API does it itself; we just need to know "is there a
-  // file at the destination?".
-  const resolved = path.resolve(process.cwd(), targetPath);
-
-  // File-arg branch: targetPath looks like `./foo.tsx`.
-  const {isFilePathArg} = await import('../../../foundation/fs/path-safety.mjs');
-  let dest;
-  if (isFilePathArg(targetPath)) {
-    dest = resolved;
-  } else {
-    const fileName = match.type === 'block'
-      ? path.basename(match.filePath)
-      : 'page.tsx';
-    dest = path.join(resolved, fileName);
-  }
-
-  return fs.existsSync(dest) ? dest : null;
-}