@fougere/cli 0.3.0-alpha.0 → 0.4.0-alpha.0

package/fronds/analysis/handlers/ExplainHandler.ts

@@ -5,6 +5,7 @@ import {
 } from '@fougere/core';
 import { relative } from 'node:path';
 import ProjectScan from '../services/ProjectScan.js';
+import { ANONYMOUS_SCHEMA_NAME, lowerFirst, type SchemaView } from '@fougere/schema';
 
 type Cardinality = NonNullable<OperationContract['cardinality']>;
 type Binding = EffectiveOperation['binding'][number];
@@ -60,6 +61,17 @@ export interface ExplainResult {
   };
 }
 
+/** What this project serves, when no single operation was named. */
+export interface ExplainListing {
+  fronds: {
+    name: string;
+    runtime: 'local' | 'remote';
+    remote: string | null;
+    operations: number;
+  }[];
+  operations: string[];
+}
+
 interface Selector {
   frond?: string;
   surface?: string;
@@ -71,17 +83,46 @@ interface Selector {
 export default class ExplainHandler {
   constructor(private projectScan: ProjectScan) {}
 
+  /** The names this project serves — the list `explain` used to spell in a refusal only. */
+  async list(input: { root?: string }): Promise<ExplainListing> {
+    const { scan, model } = await this.modelOf(input.root);
+    const remotes = scan.config.remotes ?? {};
+    const counted = new Map<string, number>();
+    for (const operation of model.operations) {
+      const frond = operation.placement.frond;
+      counted.set(frond, (counted.get(frond) ?? 0) + 1);
+    }
+
+    return {
+      fronds: scan.fronds.map((frond) => ({
+        name: frond.name,
+        runtime: remotes[frond.name] ? 'remote' as const : 'local' as const,
+        remote: remotes[frond.name] ?? null,
+        operations: counted.get(frond.name) ?? 0,
+      })).sort((a, b) => a.name.localeCompare(b.name)),
+      operations: model.operations.map((operation) => operation.id).sort(),
+    };
+  }
+
+  private async modelOf(root?: string) {
+    const scan = await this.projectScan.at(root);
+    return {
+      scan,
+      model: resolveEffectiveOperations(scan.fronds, {
+        diagnostics: scan.diagnostics,
+        remotes: scan.config.remotes,
+        adapters: scan.config.adapters,
+      }),
+    };
+  }
+
+  /** Print the contract one operation will be served under. */
   async execute(input: { operation?: string; root?: string; json?: boolean }): Promise<ExplainResult> {
     const requested = input.operation?.trim();
     if (!requested) throw new Error('Usage: fougere explain <Operation> [--json] [--root <directory>]');
 
     const selector = parseSelector(requested);
-    const scan = await this.projectScan.at(input.root);
-    const model = resolveEffectiveOperations(scan.fronds, {
-      diagnostics: scan.diagnostics,
-      remotes: scan.config.remotes,
-      adapters: scan.config.adapters,
-    });
+    const { scan, model } = await this.modelOf(input.root);
     const candidates = model.operations.filter((operation) => matches(operation, selector));
 
     if (candidates.length === 0) {
@@ -184,7 +225,7 @@ function matches(operation: EffectiveOperation, selector: Selector): boolean {
 
 function addressOf(value: string): string {
   const base = value.endsWith('Handler') ? value.slice(0, -'Handler'.length) : value;
-  return base ? base[0]!.toLowerCase() + base.slice(1) : base;
+  return lowerFirst(base);
 }
 
 function inputTypeOf(operation: EffectiveOperation): string | null {
@@ -197,11 +238,10 @@ function outputOf(operation: EffectiveOperation): ExplainResult['output'] {
   return type ? { type, cardinality: operation.cardinality ?? null } : null;
 }
 
-function schemaName(schema: unknown): string | undefined {
-  const view = schema as { name?: string; source?: { name?: string } } | undefined;
-  if (!view) return undefined;
-  if (view.name && view.name !== 'Schema') return view.name;
-  return view.source?.name;
+function schemaName(schema: SchemaView | undefined): string | undefined {
+  if (!schema) return undefined;
+  if (schema.name && schema.name !== ANONYMOUS_SCHEMA_NAME) return schema.name;
+  return schema.derivation?.sourceName;
 }
 
 function parsedOutput(raw: string | undefined): string | undefined {

package/fronds/analysis/handlers/FreezeHandler.ts

@@ -1,6 +1,6 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { describeSet, diffSet, registrationKeyOf, type SchemaBundle, type SetDiff } from '@fougere/schema';
+import { Bundle, lowerFirst, type SchemaBundle, type SchemaView, type SetDiff } from '@fougere/schema';
 import ProjectScan from '../services/ProjectScan.js';
 import { VERSIONS, chainOf } from '../versions.js';
 import type Freeze from '../entities/Freeze.js';
@@ -13,7 +13,7 @@ export interface FreezeInspection {
   /** What the step contains — absent when there is nothing before to step from. */
   step?: SetDiff;
   /** Per entity, the pairs the calculation refuses to decide. Empty means it was written. */
-  ambiguous: Record<string, Array<{ removed: string; added: string }>>;
+  ambiguous: Record<string, { removed: string; added: string }[]>;
   /** Whether anything reached the disk — false while a question stands. */
   written: boolean;
 }
@@ -54,7 +54,9 @@ export default class FreezeHandler {
       path,
       bundle,
       previous,
-      step: previous ? diffSet(previous.bundle, bundle, { renamed }) : undefined,
+      step: previous
+        ? Bundle.fromDescriptor(previous.bundle).diff(Bundle.fromDescriptor(bundle), { renamed })
+        : undefined,
     }));
 
     const ambiguous: FreezeInspection['ambiguous'] = {};
@@ -102,7 +104,9 @@ export default class FreezeHandler {
         .filter((frond) => frond.entities.length > 0)
         .map(async (frond) => ({
           path: frond.source.path,
-          bundle: describeSet(Object.fromEntries(frond.entities.map((e) => [e.name, e.entityClass]))),
+          bundle: Bundle.fromSchemas(
+            Object.fromEntries(frond.entities.map((e) => [e.name, e.entityClass])),
+          ).descriptor,
           declared: declaredRenames(frond.entities),
           previous: await previousOf(frond.source.path, input.version),
         })),
@@ -114,17 +118,17 @@ type Inspected = { previous?: { name: string }; step?: SetDiff };
 
 /**
  * What the entities state about themselves — `previous` says what a field WAS, while
- * `diff` reads old → new, so the pair is turned around here and nowhere else.
+ * `Bundle.diff` reads old to new, so the pair is turned around here and nowhere else.
  */
 function declaredRenames(
-  entities: ReadonlyArray<{ name: string; entityClass: unknown }>,
+  entities: readonly { name: string; entityClass: unknown }[],
 ): Record<string, Record<string, string>> {
   const out: Record<string, Record<string, string>> = {};
   for (const { name, entityClass } of entities) {
-    const previous = (entityClass as { previous?: Record<string, string> }).previous;
-    // Keyed as `describeSet` keys `$defs`, which is what `diffSet` reads. Spelling the
+    const previous = (entityClass as SchemaView).previous;
+    // Keyed as `Bundle.fromSchemas` keys `$defs`, which is what `Bundle.diff` reads. Spelling the
     // convention a second way here is the defect this repo has already recorded twice.
-    const key = registrationKeyOf(name);
+    const key = lowerFirst(name);
     if (previous) out[key] = Object.fromEntries(Object.entries(previous).map(([now, was]) => [was, now]));
   }
   return out;
@@ -132,12 +136,12 @@ function declaredRenames(
 
 /** Every source of an answer, folded per entity — later sources win field by field. */
 function settled(
-  sources: ReadonlyArray<Record<string, Record<string, string>>>,
+  sources: readonly Record<string, Record<string, string>>[],
   answers: Record<string, Record<string, string>>,
 ): Record<string, Record<string, string>> {
   const out: Record<string, Record<string, string>> = {};
   for (const source of [...sources, answers]) {
-    for (const [entity, pairs] of Object.entries(source)) out[entity] = { ...(out[entity] ?? {}), ...pairs };
+    for (const [entity, pairs] of Object.entries(source)) out[entity] = { ...out[entity], ...pairs };
   }
   return out;
 }

package/fronds/analysis/handlers/MigrateHandler.ts

@@ -77,7 +77,7 @@ export default class MigrateHandler {
 }
 
 /** The versions read, oldest first and each named once however many fronds cut it. */
-function versionsOf(steps: ReadonlyArray<{ version: string }>): string[] {
+function versionsOf(steps: readonly { version: string }[]): string[] {
   return [...new Set(steps.map(({ version }) => version))].sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
 }
 
@@ -90,7 +90,7 @@ function onSource(step: SetDiff, source: string, sourceOf: (entity: string) => s
 }
 
 /** Every recorded step, oldest first — the chain composes, so it is replayed whole. */
-async function stepsOf(frondPath: string): Promise<Array<{ version: string; step: SetDiff }>> {
+async function stepsOf(frondPath: string): Promise<{ version: string; step: SetDiff }[]> {
   const chain = await chainOf(frondPath);
   // The first version has a shape and no step — there was nothing before it to move from.
   return chain.flatMap(({ name, step }) => (step ? [{ version: name, step }] : []));

package/fronds/scaffold/entities/BuildFrond.ts

@@ -1,5 +1,5 @@
 import { entity, text } from '@fougere/schema';
 
 export default class BuildFrond extends entity({
-  name: text({ description: 'Frond name to build (e.g. blog)' }),
+  frond: text({ description: 'Frond name to build (e.g. blog)' }),
 }) {}

package/fronds/scaffold/entities/Call.ts

@@ -2,5 +2,5 @@ import { entity, text } from "@fougere/schema";
 
 /** `fougere call <entity>.<op> [--field value …]` — invoke one operation, print the result. */
 export default class Call extends entity({
-  target: text({ min: 1, description: "entity.op to invoke (e.g. post.create)" }),
+  operation: text({ min: 1, description: "entity.op to invoke (e.g. post.create)" }),
 }) {}

package/fronds/scaffold/entities/Sync.ts

@@ -1,6 +1,6 @@
 import { entity, text } from '@fougere/schema';
 
 export default class Sync extends entity({
-  name: text({ description: 'Frond name to sync (e.g. blog)' }),
+  frond: text({ description: 'Frond name to sync (e.g. blog)' }),
   from: text({ description: 'Remote URL (e.g. http://blog-service:3000)' }),
 }) {}

package/fronds/scaffold/handlers/BuildFrondHandler.ts

@@ -8,17 +8,17 @@ export default class BuildFrondHandler {
   private cwd = process.cwd();
 
   /** Build a frond into a standalone deployable package. */
-  async execute(input: { name: string }): Promise<{ path: string; entities: string[] }> {
+  async execute(input: { frond: string }): Promise<{ path: string; entities: string[] }> {
     const conventions = resolveConventions((await loadConfig(this.cwd)).conventions);
-    const frondDir = join(this.cwd, conventions.fronds, input.name);
+    const frondDir = join(this.cwd, conventions.fronds, input.frond);
 
     if (!existsSync(frondDir)) {
-      throw new Error(`Frond '${input.name}' not found at ${frondDir}`);
+      throw new Error(`Frond '${input.frond}' not found at ${frondDir}`);
     }
 
     const entitiesDir = join(frondDir, conventions.dirs.entities);
     if (!existsSync(entitiesDir)) {
-      throw new Error(`No ${conventions.dirs.entities}/ directory in frond '${input.name}'`);
+      throw new Error(`No ${conventions.dirs.entities}/ directory in frond '${input.frond}'`);
     }
 
     // Discover entity files
@@ -67,7 +67,7 @@ export default class BuildFrondHandler {
     const pkgPath = join(frondDir, 'package.json');
     const pkg = existsSync(pkgPath)
       ? JSON.parse(readFileSync(pkgPath, 'utf-8'))
-      : { name: frondPackage(input.name, conventions), version: '0.0.1', type: 'module' };
+      : { name: frondPackage(input.frond, conventions), version: '0.0.1', type: 'module' };
 
     pkg.exports = {
       '.': {

package/fronds/scaffold/handlers/SyncHandler.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
-import { entitySourceOf, facadeTypeSourceOf, type SchemaDescriptor } from '@fougere/schema';
+import { upperFirst, EntityTypeSource, FacadeTypeSource, type SchemaDescriptor } from '@fougere/schema';
 // The card's shape is declared once, in core, and imported here. A private copy of it
 // lived in this file and went stale the day an op stopped being a bare name: nothing
 // compared the copy to the original, so the drift cost nothing until someone read it.
@@ -26,7 +26,7 @@ export function entityClassName(name: string): string {
   const identifier = name
     .split('-')
     .filter(Boolean)
-    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .map(upperFirst)
     .join('');
   if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(identifier)) {
     throw new Error(`Entity name '${name}' cannot be represented as a TypeScript identifier`);
@@ -93,8 +93,8 @@ export default class SyncHandler {
   private cwd = process.cwd();
 
   /** Mirror a remote frond's contract into local entities. */
-  async execute(input: { name: string; from: string }): Promise<{ path: string; entities: string[]; removed: string[] }> {
-    assertSafeName('frond', input.name);
+  async execute(input: { frond: string; from: string }): Promise<{ path: string; entities: string[]; removed: string[] }> {
+    assertSafeName('frond', input.frond);
     let remoteUrl: URL;
     try {
       remoteUrl = new URL(input.from);
@@ -121,9 +121,9 @@ export default class SyncHandler {
     if (rpc.error) throw new Error(`Remote error: ${rpc.error.message}`);
     const card = identityCardOf(rpc.result);
 
-    const target = card.fronds.find((f) => f.name === input.name);
+    const target = card.fronds.find((f) => f.name === input.frond);
     if (!target) {
-      throw new Error(`Frond '${input.name}' not found on ${baseUrl}. Available: ${card.fronds.map((f) => f.name).join(', ')}`);
+      throw new Error(`Frond '${input.frond}' not found on ${baseUrl}. Available: ${card.fronds.map((f) => f.name).join(', ')}`);
     }
 
     // The consumer's own convention: a synced frond is laid out like the ones they wrote,
@@ -132,7 +132,7 @@ export default class SyncHandler {
     const entities = conventions.dirs.entities;
     const handlers = conventions.dirs.handlers;
 
-    const frondDir = join(this.cwd, '.fougere', 'remotes', input.name);
+    const frondDir = join(this.cwd, '.fougere', 'remotes', input.frond);
     const entitiesDir = join(frondDir, entities);
     const handlersDir = join(frondDir, handlers);
     mkdirSync(entitiesDir, { recursive: true });
@@ -158,7 +158,7 @@ export default class SyncHandler {
     /**
      * One card, one class.
      *
-     * `reconstruct` gives the JUDGE — validate, from, getFields — and now takes the
+     * `Card.toSchema` gives the JUDGE — validate, from, getFields — and now takes the
      * row shape as a type argument, so the same declaration gives the TYPE. Both
      * come off the same card: nothing to keep in step, and the file a consumer reads
      * has the shape of the one they would have written by hand
@@ -167,10 +167,10 @@ export default class SyncHandler {
     const writeRow = (className: string, descriptor: SchemaDescriptor): void => {
       written.add(join(entitiesDir, `${className}.ts`));
       writeFileSync(join(entitiesDir, `${className}.ts`), [
-        `import { reconstruct } from '@fougere/schema';`,
+        `import { Card } from '@fougere/schema';`,
         ``,
         `// Generated by \`fougere sync\` from ${baseUrl} — do not edit.`,
-        entitySourceOf(descriptor, { name: className }),
+        EntityTypeSource.of(descriptor).render({ name: className }),
         ``,
         `export default ${className};`,
         ``,
@@ -203,7 +203,7 @@ export default class SyncHandler {
         `// contract, and a contract that drags a runtime dependency is not one.`,
         `type Invocation = { params?: Record<string, string>; query?: Record<string, unknown>; body?: unknown; state?: Record<string, unknown> };`,
         ``,
-        facadeTypeSourceOf(ops ?? [], {
+        FacadeTypeSource.of(ops ?? []).render({
           name: `${className}Handler`,
           ...(descriptor !== undefined ? { rowType: className } : {}),
         }),
@@ -239,10 +239,10 @@ export default class SyncHandler {
 
     // Package.json
     writeFileSync(join(frondDir, 'package.json'), JSON.stringify({
-      name: frondPackage(input.name, conventions),
+      name: frondPackage(input.frond, conventions),
       version: '0.0.0-synced',
       type: 'module',
-      fougere: { frond: input.name, synced: true, source: baseUrl },
+      fougere: { frond: input.frond, synced: true, source: baseUrl },
       exports: {
         '.': './index.ts',
         [`./${entities}/*`]: `./${entities}/*.ts`,
@@ -252,10 +252,10 @@ export default class SyncHandler {
     }, null, 2) + '\n');
 
     // Update .fougere/remotes.json — central registry of synced remotes
-    this.updateRemotesRegistry(input.name, baseUrl, frondDir);
+    this.updateRemotesRegistry(input.frond, baseUrl, frondDir);
 
     // Update tsconfig paths if tsconfig.json exists (non-Nuxt projects)
-    this.updateTsconfigPaths(input.name, frondDir, conventions);
+    this.updateTsconfigPaths(input.frond, frondDir, conventions);
 
     /**
      * What the host no longer serves stops being importable here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/cli",
-  "version": "0.3.0-alpha.0",
+  "version": "0.4.0-alpha.0",
   "description": "The Fougere CLI — compose a workspace, serve a frond, call an operation.",
   "keywords": [
     "fougere",
@@ -32,7 +32,8 @@
     "dist",
     "app",
     "fronds",
-    "templates"
+    "templates",
+    "src"
   ],
   "dependencies": {
     "@clack/prompts": "^0.10.0",
@@ -40,12 +41,12 @@
     "consola": "^3.4.2",
     "jiti": "^2.4.2",
     "picocolors": "^1.1.1",
-    "@fougere/container": "0.3.0-alpha.0",
-    "@fougere/schema": "0.3.0-alpha.0",
-    "@fougere/adapter-sql": "0.3.0-alpha.0",
-    "@fougere/transport-http": "0.3.0-alpha.0",
-    "@fougere/core": "0.3.0-alpha.0",
-    "@fougere/defaults": "0.3.0-alpha.0"
+    "@fougere/adapter-sql": "0.4.0-alpha.0",
+    "@fougere/defaults": "0.4.0-alpha.0",
+    "@fougere/transport-http": "0.4.0-alpha.0",
+    "@fougere/core": "0.4.0-alpha.0",
+    "@fougere/schema": "0.4.0-alpha.0",
+    "@fougere/container": "0.4.0-alpha.0"
   },
   "devDependencies": {
     "vitest": "^4.1.0"

package/src/bin.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * fougere CLI — a Fougere app powered by citty.
+ *
+ * src/   → compiled (tsc → dist/)
+ * fronds/ → loaded at runtime by jiti (domain)
+ * app/   → loaded at runtime by jiti (presentation)
+ */
+import { createApp, setLogLevel, envLevel, type ScanResult } from '@fougere/core';
+import { scanProject, getModuleLoader, frondDirsOf, DEFAULT_CONVENTIONS } from '@fougere/core/node';
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createContainer } from '@fougere/container';
+import { ui } from './ui.js';
+import { run } from './runner.js';
+import { installLoader } from './loader.js';
+
+await installLoader(process.cwd());
+
+const cliRoot = new URL('..', import.meta.url).pathname;
+const container = createContainer();
+const terminal = ui();
+container.registerValue('ui', terminal);
+container.registerValue('cwd', process.cwd());
+
+// The CLI is a Fougere app — silence its boot chatter unless explicitly asked. The
+// threshold is SET, not only announced: a static import evaluates the logger module,
+// its env read included, before this line runs.
+process.env.FOUGERE_LOG_LEVEL ??= 'warn';
+setLogLevel(envLevel() ?? 'warn');
+
+/** The newest declaration under `fronds/`, or 0 when there is none to compare against. */
+async function newestDeclaration(root: string): Promise<number> {
+  const frondsDir = join(root, DEFAULT_CONVENTIONS.fronds);
+  const names = await readdir(frondsDir, { withFileTypes: true }).catch(() => []);
+  const dirs = names.filter((entry) => entry.isDirectory())
+    .flatMap((entry) => [
+      join(frondsDir, entry.name),
+      ...frondDirsOf(DEFAULT_CONVENTIONS).map((dir) => join(frondsDir, entry.name, dir)),
+    ]);
+
+  const times = await Promise.all(dirs.map(async (dir) => {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const stats = await Promise.all(entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.ts'))
+      .map((entry) => stat(join(dir, entry.name)).then((s) => s.mtimeMs).catch(() => 0)));
+    return Math.max(0, ...stats);
+  }));
+  return Math.max(0, ...times);
+}
+
+/**
+ * The CLI is a Fougere app, so it reads its own written-down scan like any deployment —
+ * producing the description reads the project, consuming it does not.
+ *
+ * Reading its own 44 declarations through the compiler cost 617 ms on every invocation,
+ * for a domain fixed at publish time. Staleness is decided by mtime rather than by a flag:
+ * editing a frond must not need a command, and a published package has nothing newer than
+ * its artefact.
+ */
+async function scanOf(root: string): Promise<ScanResult> {
+  const written = join(root, '.fougere/scan.generated.ts');
+  const writtenAt = await stat(written).then((s) => s.mtimeMs).catch(() => 0);
+  if (writtenAt > 0 && writtenAt >= await newestDeclaration(root)) {
+    return ((await getModuleLoader()(written)) as unknown as { scan: ScanResult }).scan;
+  }
+
+  // The only slow phase, and it announced nothing: the boot states it at `info`, which the
+  // threshold above lowers to `warn`. The terminal says it instead, and a pipe keeps its
+  // output parsable.
+  const spin = process.stdout.isTTY ? terminal.spinner('reading fronds') : undefined;
+  const scan = await scanProject(root);
+  spin?.stop(`${scan.fronds.length} frond(s)`);
+  return scan;
+}
+
+const scan = await scanOf(cliRoot);
+
+const app = await createApp({ scan, createContainer: () => container });
+
+container.registerValue('app', app);
+
+await run(app);

package/src/bridge.ts

@@ -0,0 +1,70 @@
+import { Lifecycle, Role } from '@fougere/schema';
+/**
+ * Entity → citty bridge.
+ *
+ * Converts Entity fields into citty ArgsDef.
+ * The Entity IS the CLI definition — no duplicate schema.
+ */
+import type { Fields } from '@fougere/schema';
+import { Anatomy, Visibility } from '@fougere/schema';
+import type { ArgsDef, ArgDef } from 'citty';
+
+function toKebab(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+}
+
+/** Convert an Entity's fields into citty args definition. */
+export function entityToArgs(fields: Fields): ArgsDef {
+  const args: ArgsDef = {};
+  let positionalIndex = 0;
+
+  // Axes-derived ingress membership; the CLI additionally skips ALL relations
+  // (a ref is not a flag — supplying related rows is not a CLI gesture).
+  for (const [key, field] of Object.entries(Visibility.of(fields).input)) {
+    if (Role.of(field).relation) continue;
+
+    // A `default(v)` travels as the create rule `{ value }` — citty shows it.
+    const defaultValue = Lifecycle.of(field).literal?.value;
+    const { base: shape, nullable } = Anatomy.of(field.shape);
+
+    const kebab = toKebab(key);
+    const def: ArgDef = {
+      description: field.meta?.description,
+      required: !nullable && Lifecycle.of(field).requiredAtCreate,
+    };
+
+    switch (shape?.type) {
+      case 'boolean':
+        (def as Record<string, unknown>).type = 'boolean';
+        if (defaultValue !== undefined) def.default = defaultValue as boolean;
+        break;
+      case 'number':
+      case 'integer':
+      case 'string':
+        // A closed set is citty's `enum`: the shape already names the legal values, so the
+        // refusal and the `--help` listing come from the declaration rather than a check
+        // written beside it.
+        if (shape.type === 'string' && shape.enum?.length) {
+          (def as Record<string, unknown>).type = 'enum';
+          (def as Record<string, unknown>).options = shape.enum.filter((v) => v !== null);
+        // A date-time string stays a named string — never a positional arg.
+        } else if (shape.type === 'string' && shape.format === 'date-time') {
+          (def as Record<string, unknown>).type = 'string';
+        } else if (positionalIndex === 0 && def.required && key !== 'force') {
+          // First non-bool required field becomes positional
+          (def as Record<string, unknown>).type = 'positional';
+          positionalIndex++;
+        } else {
+          (def as Record<string, unknown>).type = 'string';
+        }
+        if (defaultValue !== undefined) def.default = String(defaultValue);
+        break;
+      default:
+        (def as Record<string, unknown>).type = 'string';
+    }
+
+    args[kebab === key ? key : kebab] = def;
+  }
+
+  return args;
+}