@loomwork/scaffold 0.0.0-stage → 0.1.0

package/src/codegen.ts

@@ -0,0 +1,69 @@
+import { tsStringLiteral } from "./emit";
+
+/** kebab/snake/space → PascalCase, for deriving export names. */
+export function pascal(name: string): string {
+  return name
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("");
+}
+
+/** kebab/snake/space → camelCase, for deriving a valid function identifier. */
+export function camel(name: string): string {
+  const p = pascal(name);
+  return p.charAt(0).toLowerCase() + p.slice(1);
+}
+
+/**
+ * {@link pascal}, asserted to be a plain ASCII identifier. The template functions put it into
+ * generated source as an export name, so a name whose derivation is not an identifier
+ * (`a"; x(); //`, a leading digit) throws instead of producing code.
+ */
+export function pascalIdent(name: string): string {
+  const p = pascal(name);
+  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(p)) {
+    throw new Error(
+      `scaffold: ${JSON.stringify(name)} does not derive a valid identifier (got ${JSON.stringify(p)}); use lowercase kebab-case starting with a letter`
+    );
+  }
+  return p;
+}
+
+/**
+ * Generate the text of `loom.gen.ts` — a static module that imports the discovered
+ * flow / agent / tool / skill / schedule / memory modules and re-exports them as
+ * `flowModules` / `agentModules` / `toolModules` / `skillModules` / `scheduleModules`
+ * / `memoryModules`, for `defineConfig({ ...all six })`.
+ *
+ * This is the replay-safe form of "auto-wire from the filesystem": the imports are
+ * STATIC (fixed at build time by `loom gen`), so the set is identical on every
+ * resume / remote worker. Each `*Paths` is module specifiers relative to the
+ * generated file (extension-less), e.g. `./flows/greet/flow`, `./agents/triage`.
+ */
+export function generateRegistration(
+  flowPaths: string[],
+  agentPaths: string[] = [],
+  toolPaths: string[] = [],
+  skillPaths: string[] = [],
+  schedulePaths: string[] = [],
+  memoryPaths: string[] = [],
+  projectionPaths: string[] = []
+): string {
+  const group = (paths: string[], prefix: string, exportName: string): string[] => {
+    const imports = paths.map((p, i) => `import * as ${prefix}${i} from ${tsStringLiteral(p)};`);
+    const refs = paths.map((_, i) => `${prefix}${i}`).join(", ");
+    return [...imports, "", `export const ${exportName} = [${refs}];`, ""];
+  };
+  return [
+    "// AUTO-GENERATED by `loom gen`. Do not edit by hand.",
+    "// Static modules for defineConfig — flows/agents/tools/skills/schedules/memories/projections.",
+    ...group(flowPaths, "_f", "flowModules"),
+    ...group(agentPaths, "_a", "agentModules"),
+    ...group(toolPaths, "_t", "toolModules"),
+    ...group(skillPaths, "_s", "skillModules"),
+    ...group(schedulePaths, "_sc", "scheduleModules"),
+    ...group(memoryPaths, "_m", "memoryModules"),
+    ...group(projectionPaths, "_p", "projectionModules"),
+  ].join("\n");
+}

package/src/emit.ts

@@ -0,0 +1,72 @@
+// ── Escaping for every place a generator interpolates a spec- or model-derived string ──
+//
+// The ChangeSpec is produced by a MODEL (appgen-model) or by free-form user text
+// (parseIntent), so every string in it is untrusted. Generated TypeScript lives in the
+// user's project, which makes any unescaped interpolation a code-injection channel
+// (a newline ends a `//` comment, `*/` ends a block comment, `"` ends a string literal,
+// `${` opens a template substitution). These helpers are the ONLY sanctioned way to put
+// such text into generated source; defence is at the sink, whatever the validators did.
+
+/**
+ * Every character that must never reach generated source or a plan field raw: C0/DEL/C1
+ * controls (Cc), ALL format characters (Cf: soft hyphen, zero-width and bidi marks and
+ * overrides and isolates, BOM, interlinear annotation FFF9-FFFB, the Unicode "tag"
+ * characters U+E0000-E007F used for ASCII smuggling, musical-notation formatting
+ * U+1D173-1D17A), line and paragraph separators (Zl, Zp), lone surrogates (Cs), the
+ * combining grapheme joiner U+034F (a Mn that renders as nothing) and the unassigned
+ * U+2065 inside the bidi block. The `u` flag is what makes the astral ranges match.
+ */
+const UNSAFE_SOURCE = "[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\\p{Cs}\\u034f\\u2065]";
+const UNSAFE_CHARS = new RegExp(UNSAFE_SOURCE, "gu");
+const UNSAFE_ONE = new RegExp(UNSAFE_SOURCE, "u");
+
+/** Does `s` contain any character that must never reach generated source or a plan field? */
+export function hasUnsafeChars(s: string): boolean {
+  return UNSAFE_ONE.test(s);
+}
+
+/** `\uXXXX` for a BMP code point, a `\uD8xx\uDCxx` surrogate pair for an astral one. */
+function unicodeEscape(c: string): string {
+  const cp = c.codePointAt(0) ?? 0;
+  const u = (n: number): string => `\\u${n.toString(16).padStart(4, "0")}`;
+  if (cp <= 0xffff) return u(cp);
+  const v = cp - 0x10000;
+  return u(0xd800 + (v >> 10)) + u(0xdc00 + (v & 0x3ff));
+}
+
+/** Text for a single-line `// ...` comment: every unsafe character becomes a space. */
+export function commentText(s: string): string {
+  return s.replace(UNSAFE_CHARS, " ");
+}
+
+/** Text for a block comment: single-line as above, and a comment delimiter can never appear. */
+export function blockCommentText(s: string): string {
+  return commentText(s).replace(/\*\//g, "* /").replace(/\/\*/g, "/ *");
+}
+
+/**
+ * A complete, quoted TypeScript string literal. `JSON.stringify` escapes quotes,
+ * backslashes, C0 controls and lone surrogates; every other unsafe character (U+2028/2029,
+ * bidi, zero-width, tag characters, ...) is escaped explicitly - astral ones as a surrogate
+ * pair - so the literal is inert and reads the same in every editor.
+ */
+export function tsStringLiteral(s: string): string {
+  return JSON.stringify(s).replace(UNSAFE_CHARS, unicodeEscape);
+}
+
+/** The CONTENT (no surrounding backticks) of a template literal: `\`, backtick and `${` escaped. */
+export function templateLiteralText(s: string): string {
+  return tsStringLiteral(s)
+    .slice(1, -1)
+    .replace(/\\"/g, '"')
+    .replace(/`/g, "\\`")
+    .replace(/\$\{/g, "\\${");
+}
+
+/** One line of markdown prose: no line breaks, and markup/HTML metacharacters neutralised. */
+export function markdownText(s: string): string {
+  return commentText(s)
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/[\\`*_{}[\]<>#|!&~]/g, (c) => `\\${c}`);
+}

package/src/flowTemplates.ts

@@ -0,0 +1,353 @@
+import { pascalIdent } from "./codegen";
+import { commentText, templateLiteralText, tsStringLiteral } from "./emit";
+
+// ── Non-agentic flow templates (`loom new flow <name> --template approval|timer|saga`) ──
+//
+// The echo flow is the default. These three are the plain-workflow on-ramp: a human gate, a
+// durable timer, and compensation. Each ships a sibling test that runs on a fresh scaffold
+// (`@loomwork/testing`'s time travel drives the timers; nothing sleeps for real).
+
+export const FLOW_TEMPLATES = ["echo", "approval", "timer", "saga"] as const;
+export type FlowTemplate = (typeof FLOW_TEMPLATES)[number];
+
+export function isFlowTemplate(value: string): value is FlowTemplate {
+  return (FLOW_TEMPLATES as readonly string[]).includes(value);
+}
+
+// ── approval ──────────────────────────────────────────────────────────────────
+
+/** Suspend on a typed resume gate (`resumeSchemas`), with a 24h expiry. */
+export function approvalFlowFile(name: string): string {
+  const P = pascalIdent(name);
+  return [
+    'import { flow$, handler$, step$ } from "@loomwork/core";',
+    'import type { FlowRunner, RegisteredFlow } from "@loomwork/workflow-runtime";',
+    'import { z } from "zod";',
+    "",
+    "// The gate's contract. `resume()` parses the payload against `resumeSchemas` BEFORE it is",
+    "// appended, so a wrongly-shaped approval is refused instead of becoming a permanent fact.",
+    `const ${P}Decision = z.object({ approved: z.boolean(), approvedBy: z.string() });`,
+    "",
+    `const ${P}Apply = step$({`,
+    `  id: ${tsStringLiteral(`${name}-apply`)},`,
+    `  name: "${P} apply",`,
+    "  inputSchema: z.object({ target: z.string() }),",
+    "  outputSchema: z.object({ applied: z.boolean() }),",
+    "  handler: handler$(async (_i: { target: string }) => ({ applied: true })),",
+    "});",
+    "",
+    `type ${P}Out = { status: "applied" | "rejected" | "expired"; approvedBy?: string };`,
+    "",
+    `const runner: FlowRunner<{ target: string }, ${P}Out> = async (ctx, input) => {`,
+    "  // Durable checkpoint: the execution parks in storage (it survives a restart) until someone",
+    "  // answers the gate or the timeout passes. A timeout resumes with a TIMER_FIRED payload",
+    "  // ({ wakeAt }), which is not a decision - so parse what came back.",
+    "  const answer = await ctx.suspend<unknown>({",
+    '    on: "ApprovalGranted",',
+    "    correlationKey: input.target,",
+    "    timeout: 24 * 60 * 60 * 1000, // 24h",
+    "  });",
+    `  const parsed = ${P}Decision.safeParse(answer);`,
+    '  if (!parsed.success) return { status: "expired" };',
+    "  const decision = parsed.data;",
+    '  if (!decision.approved) return { status: "rejected", approvedBy: decision.approvedBy };',
+    `  await ctx.run(${P}Apply, { target: input.target });`,
+    '  return { status: "applied", approvedBy: decision.approvedBy };',
+    "};",
+    "",
+    `export const ${P}Flow: RegisteredFlow = {`,
+    "  definition: flow$({",
+    `    id: ${tsStringLiteral(name)},`,
+    `    name: "${P}",`,
+    '    version: "1.0.0",',
+    "    inputSchema: z.object({ target: z.string() }),",
+    '    outputSchema: z.object({ status: z.enum(["applied", "rejected", "expired"]), approvedBy: z.string().optional() }),',
+    `    steps: [${P}Apply],`,
+    `    resumeSchemas: { ApprovalGranted: ${P}Decision },`,
+    "  }),",
+    "  runner: runner as FlowRunner<unknown, unknown>,",
+    "};",
+    "",
+    "// WHO may approve is not decided here. In production wire `security.resumeAuthenticator`",
+    "// (and an `executionAuthorizer`) in defineConfig - see app/security.ts in a scaffolded app -",
+    "// so `resume()` only accepts a verified approver. The test below runs permissive on purpose.",
+    "",
+  ].join("\n");
+}
+
+export function approvalTestFile(name: string): string {
+  const P = pascalIdent(name);
+  return [
+    'import { advanceTime, createTestApp, resumeWith } from "@loomwork/testing";',
+    'import { describe, expect, it } from "vitest";',
+    `import { ${P}Flow } from "./flow";`,
+    "",
+    `describe(${tsStringLiteral(name)}, () => {`,
+    '  it("applies once approved", async () => {',
+    `    const app = createTestApp({ flows: [${P}Flow] });`,
+    "    try {",
+    `      const handle = await app.runtime.start(${P}Flow, { target: "prod-db" });`,
+    "      await handle.waitForSuspend();",
+    "      const resumed = await resumeWith(app.runtime, handle.executionId, {",
+    '        eventType: "ApprovalGranted",',
+    '        payload: { approved: true, approvedBy: "ada" },',
+    "      });",
+    "      const state = await resumed.waitForCompletion();",
+    '      expect(state.variables._output).toEqual({ status: "applied", approvedBy: "ada" });',
+    "    } finally {",
+    "      await app.close();",
+    "    }",
+    "  });",
+    "",
+    '  it("expires after 24h with no answer (time travel, no real waiting)", async () => {',
+    `    const app = createTestApp({ clock: true, flows: [${P}Flow] });`,
+    "    try {",
+    `      const handle = await app.runtime.start(${P}Flow, { target: "prod-db" });`,
+    "      await handle.waitForSuspend();",
+    "      await advanceTime(app, 24 * 60 * 60 * 1000);",
+    "      const state = await app.runtime.loadState(handle.executionId);",
+    '      expect(state?.status).toBe("completed");',
+    '      expect(state?.variables._output).toEqual({ status: "expired" });',
+    "    } finally {",
+    "      await app.close();",
+    "    }",
+    "  });",
+    "});",
+    "",
+  ].join("\n");
+}
+
+// ── timer ─────────────────────────────────────────────────────────────────────
+
+/** A durable `ctx.sleep` between two steps. */
+export function timerFlowFile(name: string): string {
+  const P = pascalIdent(name);
+  return [
+    'import { flow$, handler$, step$ } from "@loomwork/core";',
+    'import type { FlowRunner, RegisteredFlow } from "@loomwork/workflow-runtime";',
+    'import { z } from "zod";',
+    "",
+    `const ${P}Remind = step$({`,
+    `  id: ${tsStringLiteral(`${name}-remind`)},`,
+    `  name: "${P} remind",`,
+    "  inputSchema: z.object({ who: z.string() }),",
+    "  outputSchema: z.object({ reminded: z.string() }),",
+    "  handler: handler$(async (i: { who: string }) => ({ reminded: i.who })),",
+    "});",
+    "",
+    "const runner: FlowRunner<{ who: string }, { reminded: string }> = async (ctx, input) => {",
+    "  // A DURABLE sleep: the execution parks in storage and a TimerService wakes it. It survives a",
+    "  // restart and holds no process memory. For an absolute instant use `ctx.sleepUntil(epochMs)`.",
+    "  await ctx.sleep(24 * 60 * 60 * 1000); // 1 day",
+    `  return (await ctx.run(${P}Remind, { who: input.who })) as { reminded: string };`,
+    "};",
+    "",
+    `export const ${P}Flow: RegisteredFlow = {`,
+    "  definition: flow$({",
+    `    id: ${tsStringLiteral(name)},`,
+    `    name: "${P}",`,
+    '    version: "1.0.0",',
+    "    inputSchema: z.object({ who: z.string() }),",
+    "    outputSchema: z.object({ reminded: z.string() }),",
+    `    steps: [${P}Remind],`,
+    "  }),",
+    "  runner: runner as FlowRunner<unknown, unknown>,",
+    "};",
+    "",
+    "// Timers only fire where a TimerService runs: in defineConfig pass",
+    "// `timers: { store: new InMemoryTimerStore() }` (or the Sqlite/Postgres store beside your",
+    "// event store). A scaffolded app does not wire one yet.",
+    "",
+  ].join("\n");
+}
+
+export function timerTestFile(name: string): string {
+  const P = pascalIdent(name);
+  return [
+    'import { advanceTime, createTestApp } from "@loomwork/testing";',
+    'import { describe, expect, it } from "vitest";',
+    `import { ${P}Flow } from "./flow";`,
+    "",
+    "const DAY = 24 * 60 * 60 * 1000;",
+    "",
+    `describe(${tsStringLiteral(name)}, () => {`,
+    '  it("waits a day, then reminds (time travel, no real waiting)", async () => {',
+    "    // `clock: true` gives the app a controllable clock and a timer store; advanceTime moves the",
+    "    // clock and fires what became due through the real TimerService.",
+    `    const app = createTestApp({ clock: true, flows: [${P}Flow] });`,
+    "    try {",
+    `      const handle = await app.runtime.start(${P}Flow, { who: "ada" });`,
+    "      await handle.waitForSuspend();",
+    "",
+    "      await advanceTime(app, DAY - 1); // not due yet",
+    '      expect((await app.runtime.loadState(handle.executionId))?.status).toBe("suspended");',
+    "",
+    "      await advanceTime(app, 1); // due",
+    "      const state = await app.runtime.loadState(handle.executionId);",
+    '      expect(state?.status).toBe("completed");',
+    '      expect(state?.variables._output).toEqual({ reminded: "ada" });',
+    "    } finally {",
+    "      await app.close();",
+    "    }",
+    "  });",
+    "});",
+    "",
+  ].join("\n");
+}
+
+// ── saga ──────────────────────────────────────────────────────────────────────
+
+/** reserve -> charge -> ship with a compensator per forward step (`@loomwork/saga` `withSaga`). */
+export function sagaFlowFile(name: string): string {
+  const P = pascalIdent(name);
+  return [
+    'import { flow$, step$ } from "@loomwork/core";',
+    'import { withSaga } from "@loomwork/saga";',
+    'import type { FlowRunner, RegisteredFlow } from "@loomwork/workflow-runtime";',
+    'import { z } from "zod";',
+    "",
+    "// Saga steps are TOOL steps: each names a `toolId` whose effect you register on the app",
+    "// (`app.effectRuntime.register(toolId, new ToolEffect(...))`). A compensator runs under a",
+    "// derived step id, so it must resolve through its `toolId`, not through an inline `handler$`.",
+    `export const ${P}Tools = ["reserve", "unreserve", "charge", "refund", "ship"].map((t) => \`${templateLiteralText(name)}-\${t}\`);`,
+    "",
+    "// Under `security.strict` (the scaffolded app) a flow may only run the tools it is granted:",
+    `// in app/security.ts add \`...${P}Grants\` to the \`GrantTable({ ... })\`, e.g.`,
+    `//   import { ${P}Grants } from "./flows/${commentText(name)}/flow";`,
+    `//   export const authorizer = new GrantTable({ greet: ["greet-step"], ...${P}Grants });`,
+    `export const ${P}Grants = { ${tsStringLiteral(name)}: ${P}Tools };`,
+    "",
+    "const empty = z.object({});",
+    "const stepOf = (tool: string) =>",
+    "  step$({",
+    `    id: \`${templateLiteralText(name)}-\${tool}\`,`,
+    "    name: tool,",
+    `    toolId: \`${templateLiteralText(name)}-\${tool}\`,`,
+    "    inputSchema: empty,",
+    "    outputSchema: empty,",
+    "  });",
+    "",
+    "// Forward steps and their compensators (undo what the forward step did).",
+    'const reserve = stepOf("reserve");',
+    'const unreserve = stepOf("unreserve");',
+    'const charge = stepOf("charge");',
+    'const refund = stepOf("refund");',
+    'const ship = stepOf("ship");',
+    "",
+    "const runner: FlowRunner<{ orderId: string }, { ok: boolean }> = (ctx) =>",
+    "  // On any failure inside the scope, the registered compensators run in REVERSE as ordinary",
+    "  // replay-safe steps. A suspension is not a failure: it never rolls back.",
+    "  withSaga(ctx, async (saga) => {",
+    "    await saga.run(reserve, {}, unreserve);",
+    "    await saga.run(charge, {}, refund);",
+    "    await ctx.run(ship, {}); // if the carrier fails, refund then unreserve run",
+    "    return { ok: true };",
+    "  });",
+    "",
+    `export const ${P}Flow: RegisteredFlow = {`,
+    "  definition: flow$({",
+    `    id: ${tsStringLiteral(name)},`,
+    `    name: "${P}",`,
+    '    version: "1.0.0",',
+    "    inputSchema: z.object({ orderId: z.string() }),",
+    "    outputSchema: z.object({ ok: z.boolean() }),",
+    "    steps: [reserve, unreserve, charge, refund, ship],",
+    "  }),",
+    "  runner: runner as FlowRunner<unknown, unknown>,",
+    "};",
+    "",
+  ].join("\n");
+}
+
+export function sagaTestFile(name: string): string {
+  const P = pascalIdent(name);
+  return [
+    'import { ToolEffect } from "@loomwork/effect-runtime";',
+    'import { createTestApp } from "@loomwork/testing";',
+    'import { describe, expect, it } from "vitest";',
+    `import { ${P}Flow, ${P}Tools } from "./flow";`,
+    "",
+    "// Stand-ins for the real side effects: record each call, fail `ship` on demand.",
+    "function build(failShipping: boolean) {",
+    "  const ledger: string[] = [];",
+    `  const app = createTestApp({ flows: [${P}Flow] });`,
+    `  for (const toolId of ${P}Tools) {`,
+    `    const label = toolId.slice(${tsStringLiteral(`${name}-`)}.length);`,
+    "    app.effectRuntime.register(",
+    "      toolId,",
+    "      new ToolEffect(async () => {",
+    '        if (label === "ship" && failShipping) throw new Error("carrier unavailable");',
+    "        ledger.push(label);",
+    "        return {};",
+    "      })",
+    "    );",
+    "  }",
+    "  return { app, ledger };",
+    "}",
+    "",
+    `describe(${tsStringLiteral(name)}, () => {`,
+    '  it("keeps the work when every step succeeds", async () => {',
+    "    const { app, ledger } = build(false);",
+    "    try {",
+    `      const handle = await app.runtime.start(${P}Flow, { orderId: "o-1" });`,
+    "      const state = await handle.waitForCompletion();",
+    "      expect(state.variables._output).toEqual({ ok: true });",
+    '      expect(ledger).toEqual(["reserve", "charge", "ship"]);',
+    "    } finally {",
+    "      await app.close();",
+    "    }",
+    "  });",
+    "",
+    '  it("undoes the work in reverse when a later step fails", async () => {',
+    "    const { app, ledger } = build(true);",
+    "    try {",
+    `      const handle = await app.runtime.start(${P}Flow, { orderId: "o-1" });`,
+    "      await handle.waitForCompletion().catch(() => undefined); // the flow itself fails",
+    '      expect(ledger).toEqual(["reserve", "charge", "refund", "unreserve"]);',
+    "    } finally {",
+    "      await app.close();",
+    "    }",
+    "  });",
+    "});",
+    "",
+  ].join("\n");
+}
+
+/**
+ * What a developer must still do by hand after `loom new flow <name> --template <t>` - printed by
+ * the CLI, because the templates cannot edit the app's own config.
+ */
+export function templateNotes(template: FlowTemplate, name: string): string[] {
+  const P = pascalIdent(name);
+  switch (template) {
+    case "echo":
+      return [];
+    case "approval":
+      return [
+        "approval: wire `timers: { store }` in defineConfig so the 24h timeout can fire (the test provides one), and `security.resumeAuthenticator` to decide who may approve.",
+      ];
+    case "timer":
+      return [
+        "timer: wire `timers: { store }` in defineConfig so the sleep can wake (the test provides one).",
+      ];
+    case "saga":
+      return [
+        `saga: the steps are tool steps. Under \`security.strict\` add \`...${P}Grants\` (from ./flows/${commentText(name)}/flow) to the GrantTable in app/security.ts, and register an effect per tool id in \`${P}Tools\` on app.effectRuntime (the test stubs them).`,
+      ];
+  }
+}
+
+/** The flow + test contents for a non-echo template. */
+export function templateFiles(
+  template: Exclude<FlowTemplate, "echo">,
+  name: string
+): { flow: string; test: string } {
+  switch (template) {
+    case "approval":
+      return { flow: approvalFlowFile(name), test: approvalTestFile(name) };
+    case "timer":
+      return { flow: timerFlowFile(name), test: timerTestFile(name) };
+    case "saga":
+      return { flow: sagaFlowFile(name), test: sagaTestFile(name) };
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export { pascal, pascalIdent, generateRegistration } from "./codegen";
+export {
+  blockCommentText,
+  commentText,
+  hasUnsafeChars,
+  markdownText,
+  templateLiteralText,
+  tsStringLiteral,
+} from "./emit";
+export {
+  flowFile,
+  flowTestFile,
+  toolFile,
+  agentFile,
+  newFile,
+  newFiles,
+  appFiles,
+  sentinelFile,
+  importedPackages,
+  THIRD_PARTY_SPECS,
+} from "./templates";
+export {
+  CONSTRUCT_NAME,
+  kebab,
+  constructNameProblem,
+  isValidPackageName,
+  packageNameFrom,
+} from "./names";
+export { pluginFiles, pluginNextSteps, listSeams, SEAM_KEYS } from "./plugin";
+export { FLOW_TEMPLATES, isFlowTemplate, templateNotes, type FlowTemplate } from "./flowTemplates";

package/src/names.ts

@@ -0,0 +1,43 @@
+/** Names a scaffold writes into a path or a `package.json` — validated before anything is created. */
+
+/** A construct name (`loom new <kind> <name>`): kebab-case, becomes a directory / file name. */
+export const CONSTRUCT_NAME = /^[a-z][a-z0-9-]*$/;
+
+/** Best-effort kebab-case form of an arbitrary string (`"Bad Name!"` → `"bad-name"`). */
+export function kebab(input: string): string {
+  return input
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Why `name` is not an acceptable `loom new` name, or `undefined` when it is. A path
+ * separator or `..` is called out first: those escape the convention folder, which is a
+ * different mistake from a name that is merely not kebab-case.
+ */
+export function constructNameProblem(name: string): string | undefined {
+  if (/[\\/]/.test(name) || name === ".." || name === "." || /^[a-zA-Z]:/.test(name)) {
+    return `"${name}" is a path, not a name — a name may not contain path separators or "..", it would write outside the convention folder`;
+  }
+  if (CONSTRUCT_NAME.test(name)) return undefined;
+  const k = kebab(name);
+  const hint = CONSTRUCT_NAME.test(k) ? ` — did you mean "${k}"?` : "";
+  return `invalid name "${name}": use lowercase kebab-case matching ${CONSTRUCT_NAME.source}${hint}`;
+}
+
+/** npm's rules for a package name, unscoped or `@scope/name` (lowercase, URL-safe, no leading `.`/`_`). */
+export function isValidPackageName(name: string): boolean {
+  return (
+    name.length > 0 &&
+    name.length <= 214 &&
+    /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/.test(name)
+  );
+}
+
+/** A valid npm name derived from a directory name, or `undefined` if nothing usable remains. */
+export function packageNameFrom(dirName: string): string | undefined {
+  const k = kebab(dirName);
+  return isValidPackageName(k) ? k : undefined;
+}