tina4-nodejs 3.13.120 → 3.13.121

package/packages/cli/src/bin.ts

@@ -345,10 +345,13 @@ export const COMMANDS: Record<string, CommandSpec> = {
     summary: "Run pending SQL migrations",
   },
   "migrate:create": {
-    handler: async (a) => { await createMigration(a.join(" ") || undefined); },
+    // Pass the full argv through so `migrate:create "add users" --json --dry-run`
+    // reaches the same envelope machinery as `generate migration ...` (ADR-0063).
+    // The delegation itself lives in commands/migrateCreate.ts.
+    handler: async (a) => { await createMigration(a); },
     usage: "<desc>",
     args: ["description"],
-    summary: "Create a new migration file",
+    summary: "Create a new migration file (delegates to generate migration)",
   },
   "migrate:status": {
     handler: async (a) => { await migrateStatus(a[0]); },

package/packages/cli/src/commands/generate.ts

@@ -306,24 +306,41 @@ function toRelPath(absPath: string): string {
   return sep === "/" ? rel : rel.split(sep).join("/");
 }
 
-// Line-anchored `// tina4:edit LABEL` marker regex.
+// Line-anchored `tina4:edit LABEL` marker regex (multi-style, ADR-0063 v1.1).
 //
-// Line-anchored (`^\s*//`) so the marker must be at the START of a code line
-// (after optional whitespace) — a marker embedded inside a template string
-// literal never falsely matches. LABEL is captured greedily until end of
-// line, then trimmed on push.
-const TINA4_EDIT_MARKER = /^\s*\/\/\s*tina4:edit\s+(.+?)\s*$/;
+// Line-anchored (`^\s*<comment-lead>`) so the marker must be at the START of
+// a code line (after optional whitespace) — a marker embedded inside a
+// template string literal never falsely matches. LABEL is captured greedily
+// until end of line (or the closing `#}` for a Twig comment), then trimmed
+// on push. Four comment styles are recognised, one regex per style — bundled
+// into one alternation so the scanner is O(lines):
+//
+//   // tina4:edit LABEL            TS/JS/C/Java/Rust  (existing)
+//   #  tina4:edit LABEL            Python/Ruby/shell  (parity)
+//   -- tina4:edit LABEL            SQL migrations
+//   {# tina4:edit LABEL #}         Twig / Frond templates
+//
+// Ports the same shape PHP uses in `bin/tina4php::collectEditHintsFromContent`
+// (`~(?://|--|\{#)\s*tina4:edit\s+(.+?)(?:\s*#\})?\s*$~`). The `#` bare-
+// comment style is added on top so a Ruby/Python-style template (none exist
+// today, but the scanner is now language-agnostic) is covered too.
+const TINA4_EDIT_MARKER = /^\s*(?:\/\/|--|\{#|#)\s*tina4:edit\s+(.+?)(?:\s*#\})?\s*$/;
 
 /**
- * Scan `content` for `// tina4:edit …` markers and record one EditHint per
- * match against the given absolute path. Called from every `writeFileSafe`
- * — including under `--dry-run` — so the envelope promises the same hints in
- * preview and post-write. Files whose extension is not TS/JS are skipped
- * (the marker syntax is TS/JS specific — `.sql` and `.twig` templates never
- * carry markers).
+ * Scan `content` for `tina4:edit …` markers (any of the 4 comment styles)
+ * and record one EditHint per match against the given absolute path. Called
+ * from every `writeFileSafe` — including under `--dry-run` — so the envelope
+ * promises the same hints in preview and post-write.
+ *
+ * File-extension gate keeps the scan cheap: only text/code files where a
+ * marker could reasonably live are opened. TS/JS + SQL + Twig cover every
+ * template the generator emits today; expanded here (from TS/JS-only in
+ * 3.13.120) so `generate form`, `generate view` and `generate migration`
+ * carry `edit_hints[]` rather than returning `[]` (parity with PHP, whose
+ * regex has always been language-agnostic).
  */
 function captureEditHints(absPath: string, content: string): void {
-  if (!/\.(ts|tsx|js|mjs|cjs|jsx)$/.test(absPath)) return;
+  if (!/\.(ts|tsx|js|mjs|cjs|jsx|sql|twig|html\.twig)$/.test(absPath)) return;
   const relPath = toRelPath(absPath);
   const lines = content.split("\n");
   for (let i = 0; i < lines.length; i++) {
@@ -454,6 +471,10 @@ export function parseCliArgs(args: string[]): { flags: Record<string, string | b
   const booleanFlags = new Set([
     "no-browser", "no-reload", "production", "managed", "all", "clear",
     "public", "no-migration",
+    // Suppress the co-emitted migration test (used by the migrate:create
+    // delegation — a plain migrate:create is "just a migration, no test",
+    // matching its pre-3.13.121 UX now that it routes through generate migration).
+    "no-test",
     // Resolution transparency (Feature B, 3.13.117): both accept NO value.
     "json", "dry-run",
   ]);
@@ -573,7 +594,7 @@ export const GENERATORS: Record<string, GeneratorSpec> = {
   model:      { handler: generateModel,                     usage: '<Name> [--fields "name:string,price:float"]', summary: "ORM model + matching migration" },
   route:      { handler: generateRoute,                     usage: "<name> [--model Name] [--public]",            summary: "CRUD route file, secure by default (--public opens writes)" },
   crud:       { handler: generateCrud,                      usage: '<Name> [--fields "..."] [--public]',          summary: "Model + migration + routes + form + view + test" },
-  migration:  { handler: (n, f) => generateMigration(n, f), usage: "<description>",                                summary: "Timestamped migration file (UP/DOWN)" },
+  migration:  { handler: (n, f) => generateMigration(n, f, undefined, undefined, !f["no-test"]), usage: "<description>",                                summary: "Timestamped migration file (UP/DOWN)" },
   middleware: { handler: generateMiddleware,                usage: "<Name>",                                       summary: "Middleware with before/after hooks" },
   test:       { handler: generateTest,                      usage: "<name> [--model Name]",                        summary: "Test file" },
   form:       { handler: generateForm,                      usage: '<Name> [--fields "..."]',                      summary: "Form template with inputs matching model fields" },
@@ -761,6 +782,53 @@ export async function generate(what: string, name: string, extraArgs: string[] =
   printResolution();
 }
 
+/**
+ * Programmatic entry point for in-process consumers (MCP tools, tests, hosted
+ * agents) — does everything `generate()` does EXCEPT print.
+ *
+ * Reset the resolution → dispatch to the requested generator → populate `next[]`
+ * → return the envelope. Files still land on disk (unless `--dry-run` is passed
+ * in `extraArgs`); only the human "Created …" per-file log and the
+ * `printResolution()` output are suppressed (via `jsonMode: true`, the same
+ * suppression `--json` uses on the CLI).
+ *
+ * Used by the MCP `migration_create` tool (packages/core/src/mcp.ts) so the
+ * ADR-0063 `generate_v1_1` envelope drives every surface (CLI, MCP, tests)
+ * without a subprocess round-trip.
+ */
+export async function generateProgrammatic(
+  what: string,
+  name: string,
+  extraArgs: string[] = [],
+): Promise<ResolutionEnvelope> {
+  const spec = GENERATORS[what];
+  if (!spec) throw new Error(`Unknown generator: ${what} (available: ${GENERATOR_LIST})`);
+
+  const { flags } = parseCliArgs(extraArgs);
+  const dryRun = Boolean(flags["dry-run"]);
+  // jsonMode:true suppresses writeFileSafe's per-file console.log so nothing
+  // leaks to stdout (which the JSON-RPC caller would parse as tool output).
+  // Files are still written — jsonMode gates PRINTS only, not disk writes.
+  resetResolution(what, { name, fields: (flags.fields as string) ?? null }, { dryRun, jsonMode: true });
+
+  spec.handler(name, flags);
+
+  // v1.1 (ADR-0063): populate `resolution.next[]` from the per-verb curator —
+  // same logic `generate()` runs, using the RESOLVED table_name when the
+  // dispatched handler recorded one (avoids a duplicate reserved_word
+  // transformation on the envelope).
+  const nextFn = NEXT_STEPS[what];
+  if (nextFn) {
+    const resolvedTable = __resolution.body.table_name
+      ?? (name
+        ? (SQL_RESERVED_TABLE_NAMES.has(toSnake(name)) ? pluralizeReserved(toSnake(name)) : toSnake(name))
+        : "");
+    setNextSteps(nextFn({ name: name || "", table: resolvedTable }));
+  }
+
+  return currentResolution();
+}
+
 // ── Model ───────────────────────────────────────────────────────────
 
 function generateModel(name: string, flags: Record<string, string | boolean>, emitTest = true): void {
@@ -1129,7 +1197,7 @@ function generateCrud(name: string, flags: Record<string, string | boolean>): vo
 
 // ── Migration ───────────────────────────────────────────────────────
 
-function generateMigration(
+export function generateMigration(
   name: string,
   flags: Record<string, string | boolean>,
   fieldsOverride?: Array<[string, string]>,
@@ -1185,6 +1253,15 @@ function generateMigration(
   let upSql: string;
   let downSql: string;
 
+  // ADR-0063 (scaffolding envelope v1.1): `-- tina4:edit <label>` markers
+  // sit above each SQL block so an operator (or an AI agent) can grep to
+  // the genuine first-edit spot. Wording mirrors Ruby's `generate_migration`
+  // + PHP's `sqlEditHintMarker` calls for cross-language parity. The create-
+  // branch marker sits INSIDE the column-list parentheses but OUTSIDE
+  // `colLines.join(",\n")` so its trailing `,` does not become part of the
+  // parsed label (the migration runner's splitStatements strips `--` line
+  // comments, so a comma-less marker line inside a DDL body is still
+  // syntactically inert on every engine).
   if (isCreate) {
     const colLines = ["    id INTEGER PRIMARY KEY AUTOINCREMENT"];
     for (const [fname, ftype] of fields) {
@@ -1194,11 +1271,20 @@ function generateMigration(
     }
     colLines.push("    created_at TEXT DEFAULT CURRENT_TIMESTAMP");
 
-    upSql = `CREATE TABLE IF NOT EXISTS ${table} (\n${colLines.join(",\n")}\n);`;
-    downSql = `DROP TABLE IF EXISTS ${table};`;
+    upSql =
+      `CREATE TABLE IF NOT EXISTS ${table} (\n` +
+      `    -- tina4:edit  add columns beyond id + created_at\n` +
+      `${colLines.join(",\n")}\n);`;
+    downSql =
+      `-- tina4:edit  mirror the CREATE's added columns in the rollback\n` +
+      `DROP TABLE IF EXISTS ${table};`;
   } else {
-    upSql = `-- Write your UP migration SQL here\n-- Example: ALTER TABLE ${table} ADD COLUMN new_col TEXT DEFAULT '';`;
-    downSql = `-- Write your DOWN rollback SQL here\n-- Example: ALTER TABLE ${table} DROP COLUMN new_col;`;
+    upSql =
+      `-- tina4:edit  write your UP migration SQL here\n` +
+      `-- Example: ALTER TABLE ${table} ADD COLUMN new_col TEXT DEFAULT '';`;
+    downSql =
+      `-- tina4:edit  write your DOWN rollback SQL here\n` +
+      `-- Example: ALTER TABLE ${table} DROP COLUMN new_col;`;
   }
 
   const now = isoNow();
@@ -1470,12 +1556,18 @@ function generateForm(name: string, flags: Record<string, string | boolean>): vo
     }
   }
 
+  // ADR-0063 (scaffolding envelope v1.1): `{# tina4:edit <label> #}` is the
+  // Twig-comment partner of `// tina4:edit` in TS/JS. Baked at a genuine
+  // first-edit spot so an operator (or an AI agent) can grep to a real
+  // customisation point instead of scanning the whole file. Marker wording
+  // mirrors Ruby's `generate_form` for cross-language parity.
   const content =
     `{% extends "base.twig" %}\n` +
     `{% block title %}${name} {% if item.id %}Edit{% else %}Create{% endif %}{% endblock %}\n` +
     `{% block content %}\n` +
     `<div class="container mt-4">\n` +
     `    <h1>{% if item.id %}Edit ${name}{% else %}Create ${name}{% endif %}</h1>\n` +
+    `    {# tina4:edit  restyle the form beyond the scaffolded defaults #}\n` +
     `    <form method="post" action="/api/${routeName}{% if item.id %}/{{ item.id }}{% endif %}">\n` +
     `        {{ form_token() }}\n` +
     fieldHtml +
@@ -1507,11 +1599,16 @@ function generateView(name: string, flags: Record<string, string | boolean>): vo
   const th = cols.map((c) => `                <th>${c.replace(/_/g, " ").replace(/\b\w/g, (ch) => ch.toUpperCase())}</th>`).join("\n");
   const td = cols.map((c) => `                <td>{{ item.${c} }}</td>`).join("\n");
 
+  // ADR-0063 (scaffolding envelope v1.1): `{# tina4:edit <label> #}` markers
+  // sit at each template's genuine first-edit spot (list = customise the
+  // table; detail = extend the record's view). Wording mirrors Ruby's
+  // `generate_view` for cross-language parity.
   const listContent =
     `{% extends "base.twig" %}\n` +
     `{% block title %}${name}s{% endblock %}\n` +
     `{% block content %}\n` +
     `<div class="container mt-4">\n` +
+    `    {# tina4:edit  add sort / filter / pagination controls to the list #}\n` +
     `    <div class="d-flex justify-content-between align-items-center mb-3">\n` +
     `        <h1>${name}s</h1>\n` +
     `        <a href="/${routeName}/create" class="btn btn-primary">Add ${name}</a>\n` +
@@ -1553,6 +1650,7 @@ function generateView(name: string, flags: Record<string, string | boolean>): vo
     `{% block title %}${name} Detail{% endblock %}\n` +
     `{% block content %}\n` +
     `<div class="container mt-4">\n` +
+    `    {# tina4:edit  extend the detail view with related records or actions #}\n` +
     `    <div class="d-flex justify-content-between align-items-center mb-3">\n` +
     `        <h1>${name} #{{ item.id }}</h1>\n` +
     `        <div>\n` +

package/packages/cli/src/commands/migrateCreate.ts

@@ -8,53 +8,48 @@
  * Creates both:
  *   migrations/YYYYMMDDHHMMSS_description.sql       (up migration)
  *   migrations/YYYYMMDDHHMMSS_description.down.sql   (rollback)
+ *
+ * 3.13.121 (ADR-0063): this is a thin delegation to `generate migration` so a
+ * scaffolded migration has ONE shape and ONE envelope regardless of whether
+ * the developer typed `tina4 migrate:create` or `tina4 generate migration`.
+ * The two file paths emitted here (`_desc.sql` + `_desc.down.sql`) and the
+ * schema-awareness on `create_X` names are unchanged; the delegation adds the
+ * ADR-0063 `generate_v1_1` envelope, `--json` / `--dry-run` support, and the
+ * `edit_hints[]` / `next[]` machinery for free. `--no-test` preserves the
+ * pre-3.13.121 UX (just a migration, no co-emitted test).
  */
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { generate } from "./generate.js";
+
+export async function createMigration(args: string[] = []): Promise<void> {
+  // Split flags from the description so `tina4 migrate:create "add users"
+  // --json --dry-run` reaches the same envelope machinery as its
+  // `tina4 generate migration` twin (see test/migrateCreateEnvelopeParity.test.ts).
+  const positionals: string[] = [];
+  const flags: string[] = [];
+  for (const arg of args) {
+    if (arg.startsWith("--")) flags.push(arg);
+    else positionals.push(arg);
+  }
+  const description = positionals.join(" ").trim();
 
-export async function createMigration(description?: string): Promise<void> {
   if (!description) {
     console.error("  Usage: tina4 migrate:create <description>");
     console.error('  Example: tina4 migrate:create "create users table"');
     process.exit(1);
   }
 
-  const dir = resolve("migrations");
-
-  // Ensure migrations/ exists
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-
-  // Sanitise description for filename
-  const safeName = description
+  // Sanitise the description into a filename-safe slug BEFORE delegation.
+  // Preserves migrate:create's pre-3.13.121 UX: `migrate:create "add users"`
+  // still yields `${ts}_add_users.sql` (space -> underscore, lowercased),
+  // never a filename with a bare space. `generate migration` takes its name
+  // verbatim by design; migrate:create is the human-friendly front door.
+  const safeDescription = description
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "_")
     .replace(/^_|_$/g, "");
 
-  // Use YYYYMMDDHHMMSS timestamp prefix
-  const now = new Date();
-  const timestamp = [
-    now.getFullYear(),
-    String(now.getMonth() + 1).padStart(2, "0"),
-    String(now.getDate()).padStart(2, "0"),
-    String(now.getHours()).padStart(2, "0"),
-    String(now.getMinutes()).padStart(2, "0"),
-    String(now.getSeconds()).padStart(2, "0"),
-  ].join("");
-
-  const upFileName = `${timestamp}_${safeName}.sql`;
-  const downFileName = `${timestamp}_${safeName}.down.sql`;
-  const upPath = join(dir, upFileName);
-  const downPath = join(dir, downFileName);
-
-  const upTemplate = `-- Migration: ${description}\n-- Created: ${now.toISOString()}\n\n`;
-  const downTemplate = `-- Rollback: ${description}\n-- Created: ${now.toISOString()}\n\n`;
-
-  writeFileSync(upPath, upTemplate, "utf-8");
-  writeFileSync(downPath, downTemplate, "utf-8");
-
-  console.log(`  Created migration:  ${upFileName}`);
-  console.log(`  Created rollback:   ${downFileName}`);
-  console.log(`  Path: ${dir}`);
+  // Delegate to `generate migration` with --no-test so migrate:create stays
+  // "just a migration, no test" — its pre-3.13.121 semantics — while getting
+  // the ADR-0063 envelope, edit_hints[], next[] and --json/--dry-run for free.
+  await generate("migration", safeDescription, ["--no-test", ...flags]);
 }