@beignet/cli 0.0.47 → 0.0.49

package/skills/app-structure/SKILL.md

@@ -8,6 +8,9 @@ description: "Maintain Beignet app structure with @beignet/cli: deterministic ap
 Use this skill when working with Beignet apps through `@beignet/cli`. Prefer
 generators and validation commands before hand-editing framework wiring.
 
+Beignet apps require Node.js 22.12 or newer. Bun 1.3.14 or newer is supported
+for Beignet commands.
+
 ## Starter Sources
 
 Generated apps include:
@@ -64,6 +67,7 @@ changing `infra/db/schema/`, run the app's db lifecycle commands:
 ```bash
 beignet db generate
 beignet db migrate
+beignet db status
 ```
 
 ## Explicit Registration
@@ -74,6 +78,10 @@ Hand-written files do not run until registered:
 - schedules -> `server/schedules.ts`
 - tasks -> `server/tasks.ts`
 - outbox events/jobs -> `server/outbox.ts`
+- outbox jobs also require `jobs: JobDispatcherPort` in `AppPorts`, bound
+  directly or deferred to a provider; `make job` installs an app-owned inline
+  dispatcher only when none is already wired, and a later Inngest or BullMQ
+  preset replaces only that marked generated fallback
 - listeners -> `server/listeners.ts` plus `registerListeners(...)` in server provider wiring
 - queued notifications -> `server/notifications.ts`, plus the delivery job in
   every job worker or outbox registry that can receive it
@@ -94,6 +102,18 @@ Feature route groups should import the app-bound `defineRouteGroup` from
 `lib/routes.ts`. `doctor` checks both that feature routes use that builder and
 that the builder itself calls `createRoutes<AppContext>()`.
 
+`beignet routes` recognizes contract factories through value imports from
+`@beignet/core/contracts`, including named aliases and namespace imports. It
+ignores same-named methods on unrelated objects.
+
+Doctor also reports an outbox registry containing jobs when the configured
+ports and port-wiring files do not declare and bind or defer the `jobs` port.
+This finding is diagnostic-only because choosing a production dispatcher is an
+application decision. Keep the registry's `jobs` entries and the `jobs` port
+explicit; doctor reports indeterminate registry or port-wiring shapes when
+they prevent it from verifying required wiring, and `make job` stops instead
+of replacing spread- or helper-based wiring it cannot verify.
+
 Run `beignet doctor --strict` after hand edits. Use
 `beignet doctor --fix --dry-run` to inspect exact low-risk repair patches, then
 apply the returned plan with `beignet doctor --fix --plan <plan-id>` and
@@ -148,20 +168,38 @@ registration status, doctor/lint findings, and unresolved references. Use
 The graph resolves local modules with the full TypeScript `baseUrl` and `paths`
 configuration. Treat `local_import_unresolved` and
 `contract_declaration_unresolved` as real blind spots to fix, not absent
-relationships. Registration diagnostics carry `subject.file` and
-`subject.exportName` so agents can act on the declaration without parsing the
-diagnostic message.
+relationships. This includes direct and contract-group declarations whose
+method, path, or group prefix is dynamic. Local fluent-builder aliases and
+named local exports retain the exported declaration identity. Registration
+diagnostics carry `subject.file` and `subject.exportName` so agents can act on
+the declaration without parsing the diagnostic message.
 
 `beignet lint` enforces dependency direction:
 
 - domain and use cases must not import infra, routes, server, providers, React,
   or client modules
-- client-reachable modules must not import server-only code
+- contracts, schemas, and client-reachable modules must not import server-only
+  code
 - routes may import contracts, use cases, policies, and app context types, but
   not concrete infra
+- contract query schemas require an explicit second `.query(schema, transport)`
+  argument built with `defineQueryTransport`; the shared transport, not schema
+  coercion, defines client, server, and OpenAPI URL serialization
+- agent capabilities may adapt existing use cases; use cases, workflows, seeds,
+  and feature-root helpers must not depend back on agent adapters
+- seeds should compose factories and context ports rather than concrete infra,
+  providers, UI, or runtime composition
+- TypeScript imports, re-exports, `require()`, import assignments, and literal
+  dynamic imports all participate in the same graph
+- feature-root helpers are classified and followed transitively, so they cannot
+  hide a forbidden dependency; computed module references in constrained layers
+  fail when lint cannot verify their destination
+- near-miss canonical layers and known aliases such as `usecases/` and
+  `events/` report the same expected path from lint and doctor
 
 `beignet doctor --strict` reports structure and registration drift:
 
+- contract query schemas without an explicit transport
 - missing route group registration
 - route files that bypass the configured app-bound route builder
 - route builders that are not bound with `createRoutes<AppContext>()`
@@ -195,7 +233,7 @@ Generated apps register:
 }
 ```
 
-The MCP server exposes `app_map`, `explain`, `check`, `db`,
+The MCP server exposes `app_map`, `explain`, `check`, `db`, `db_status`,
 `db_schema_sync`, `task_run`, `schedule_run`, `outbox_inspect`, `outbox_run`,
 `routes`, `doctor`, `doctor_fix_plan`, `doctor_fix`, `lint`, `make`, and
 `provider_add`. It also publishes `beignet://app/guidance` and the
@@ -210,10 +248,15 @@ concept or diagnostic and returns the same deterministic result as
 `beignet explain <kind> <target> --json`. Explain accepts every app-map node
 kind plus `diagnostic`; targets may use stable IDs, runtime or declaration
 names, source selectors, and applicable aliases. `check` accepts optional
-`{ preflight?: boolean, timeoutMs?: number }`, bounds failure output, cancels
-the active script with the MCP request, and returns the same versioned result
-as `beignet check --json`. It does not apply Beignet fixes, but app package
-scripts retain their normal side effects. `db` accepts
+`{ preflight?: boolean, preflightConnect?: boolean, connectTimeoutMs?: number, timeoutMs?: number }`.
+Connected preflight adds migration status and dependency health checks. Check
+bounds failure output, cancels the active script with the MCP request, and
+returns the same versioned result as `beignet check --json`. It does not apply
+Beignet fixes, but app package scripts retain their normal side effects. The
+target package must declare `@beignet/core`, `@beignet/next`, or `@beignet/web`
+as a runtime dependency. The root must also contain `app-context.ts` or
+`beignet.config.*`, or the canonical `features/` and `server/index.ts` pair;
+otherwise check stops before analysis or scripts. `db` accepts
 `{ command: "generate" | "migrate" | "seed" | "reset", dryRun?, timeoutMs? }`
 and returns the matching versioned `beignet db <command> --json` report with
 bounded output, cancellation, and process-tree timeouts. `db_schema_sync`
@@ -221,7 +264,9 @@ accepts `{ dialect?, tables?, output?, dryRun? }` and returns the matching
 `beignet db schema sync --json` report. For lifecycle commands, `dryRun`
 validates and reports the app-owned script without executing it; it does not
 simulate SQL or data changes. `reset` remains environment-sensitive even
-though the generated entrypoint has a production guard. `task_run` and
+though the generated entrypoint has a production guard. `db_status` runs the
+app-owned read-only migration inspection: current exits 0, pending exits 2,
+and inspection failures use another non-zero exit. `task_run` and
 `schedule_run` execute registered app workflows. Use `outbox_inspect` for
 read-only `list` and `show`, and `outbox_run` for state-changing `drain`,
 `requeue`, `purge`, and `prune`; purge and prune support `dryRun`. Operational
@@ -255,7 +300,7 @@ When MCP is available, call `check` after edits to run the full validation loop
 through the app-local CLI without reconstructing these commands individually.
 For a generated persistent resource, the complete structured workflow is
 `app_map` → `explain` → `make` → `db_schema_sync` when provider tables changed
-→ `db` generate → `db` migrate → the relevant `task_run`, `schedule_run`, or
+→ `db` generate → `db` migrate → `db_status` → the relevant `task_run`, `schedule_run`, or
 outbox tool when operational work is required → `check`.
 
 For generated app template changes inside the Beignet monorepo, also run:

package/src/analysis/contract-factories.ts

@@ -0,0 +1,256 @@
+import ts from "typescript";
+
+const contractFactoryModule = "@beignet/core/contracts";
+
+export type ContractFactoryName = "defineContract" | "defineContractGroup";
+
+export type ContractFactoryBindings = {
+  localNames: Record<ContractFactoryName, Set<string>>;
+  namespaceNames: Set<string>;
+};
+
+export type ContractBindingNames = {
+  contracts: Set<string>;
+  groups: Set<string>;
+};
+
+type ContractCall = {
+  name: string;
+  node: ts.CallExpression;
+};
+
+type ContractCallChain = {
+  baseIdentifier?: string;
+  rootCall?: ContractCall;
+  calls: ContractCall[];
+};
+
+const contractGroupMethods = new Set([
+  "defineContractGroup",
+  "deprecated",
+  "errors",
+  "headers",
+  "meta",
+  "namespace",
+  "prefix",
+  "responses",
+]);
+
+const httpContractMethods = new Set([
+  "delete",
+  "get",
+  "head",
+  "options",
+  "patch",
+  "post",
+  "put",
+]);
+
+export function contractFactoryBindings(
+  sourceFile: ts.SourceFile,
+): ContractFactoryBindings {
+  const bindings: ContractFactoryBindings = {
+    localNames: {
+      defineContract: new Set(),
+      defineContractGroup: new Set(),
+    },
+    namespaceNames: new Set(),
+  };
+
+  for (const statement of sourceFile.statements) {
+    if (
+      !ts.isImportDeclaration(statement) ||
+      !ts.isStringLiteral(statement.moduleSpecifier) ||
+      statement.moduleSpecifier.text !== contractFactoryModule ||
+      !statement.importClause ||
+      statement.importClause.isTypeOnly
+    ) {
+      continue;
+    }
+
+    const namedBindings = statement.importClause.namedBindings;
+    if (namedBindings && ts.isNamespaceImport(namedBindings)) {
+      bindings.namespaceNames.add(namedBindings.name.text);
+      continue;
+    }
+    if (!namedBindings || !ts.isNamedImports(namedBindings)) continue;
+
+    for (const element of namedBindings.elements) {
+      if (element.isTypeOnly) continue;
+      const importedName = (element.propertyName ?? element.name).text;
+      if (!isContractFactoryName(importedName)) continue;
+      bindings.localNames[importedName].add(element.name.text);
+    }
+  }
+
+  return bindings;
+}
+
+export function isImportedContractFactoryCall(
+  call: ts.CallExpression,
+  name: ContractFactoryName,
+  bindings: ContractFactoryBindings,
+): boolean {
+  const callee = unwrapExpression(call.expression);
+  if (ts.isIdentifier(callee)) {
+    return bindings.localNames[name].has(callee.text);
+  }
+  if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== name) {
+    return false;
+  }
+
+  const receiver = unwrapExpression(callee.expression);
+  return (
+    ts.isIdentifier(receiver) && bindings.namespaceNames.has(receiver.text)
+  );
+}
+
+/** Follow imported factories through local group and contract builder aliases. */
+export function contractBindingNames(
+  sourceFile: ts.SourceFile,
+  bindings: ContractFactoryBindings,
+): ContractBindingNames {
+  const declarations = sourceFile.statements
+    .filter(ts.isVariableStatement)
+    .flatMap((statement) => [...statement.declarationList.declarations]);
+  const names: ContractBindingNames = {
+    contracts: new Set(),
+    groups: new Set(),
+  };
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const declaration of declarations) {
+      if (
+        !ts.isIdentifier(declaration.name) ||
+        !declaration.initializer ||
+        names.contracts.has(declaration.name.text) ||
+        names.groups.has(declaration.name.text)
+      ) {
+        continue;
+      }
+      const chain = contractCallChain(declaration.initializer);
+      if (!chain) continue;
+
+      if (
+        contractFactoryCall(chain, "defineContract", bindings) ||
+        (chain.baseIdentifier && names.contracts.has(chain.baseIdentifier))
+      ) {
+        names.contracts.add(declaration.name.text);
+        changed = true;
+        continue;
+      }
+
+      if (!isContractGroupDerived(chain, bindings, names.groups)) continue;
+      if (chain.calls.some((call) => httpContractMethods.has(call.name))) {
+        names.contracts.add(declaration.name.text);
+        changed = true;
+        continue;
+      }
+
+      if (chain.calls.some((call) => !contractGroupMethods.has(call.name))) {
+        continue;
+      }
+      names.groups.add(declaration.name.text);
+      changed = true;
+    }
+  }
+
+  return names;
+}
+
+/** Determine whether an expression declares a direct or group-built contract. */
+export function isImportedContractDeclaration(
+  expression: ts.Expression,
+  bindings: ContractFactoryBindings,
+  names: ContractBindingNames,
+): boolean {
+  const chain = contractCallChain(expression);
+  if (!chain) return false;
+  if (
+    contractFactoryCall(chain, "defineContract", bindings) ||
+    (chain.baseIdentifier && names.contracts.has(chain.baseIdentifier))
+  ) {
+    return true;
+  }
+  return (
+    isContractGroupDerived(chain, bindings, names.groups) &&
+    chain.calls.some((call) => httpContractMethods.has(call.name))
+  );
+}
+
+function isContractGroupDerived(
+  chain: ContractCallChain,
+  bindings: ContractFactoryBindings,
+  groupNames: ReadonlySet<string>,
+): boolean {
+  return Boolean(
+    contractFactoryCall(chain, "defineContractGroup", bindings) ||
+      (chain.baseIdentifier && groupNames.has(chain.baseIdentifier)),
+  );
+}
+
+function contractFactoryCall(
+  chain: ContractCallChain,
+  name: ContractFactoryName,
+  bindings: ContractFactoryBindings,
+): ContractCall | undefined {
+  const calls = chain.rootCall ? [chain.rootCall, ...chain.calls] : chain.calls;
+  return calls.find((call) =>
+    isImportedContractFactoryCall(call.node, name, bindings),
+  );
+}
+
+function contractCallChain(
+  rawExpression: ts.Expression,
+): ContractCallChain | undefined {
+  const calls: ContractCall[] = [];
+  let expression = rawExpression;
+
+  while (true) {
+    expression = unwrapExpression(expression);
+    if (ts.isPropertyAccessExpression(expression)) {
+      expression = expression.expression;
+      continue;
+    }
+    if (ts.isCallExpression(expression)) {
+      const callee = unwrapExpression(expression.expression);
+      if (ts.isPropertyAccessExpression(callee)) {
+        calls.unshift({ name: callee.name.text, node: expression });
+        expression = callee.expression;
+        continue;
+      }
+      if (ts.isIdentifier(callee)) {
+        return {
+          baseIdentifier: callee.text,
+          rootCall: { name: callee.text, node: expression },
+          calls,
+        };
+      }
+      return undefined;
+    }
+    if (ts.isIdentifier(expression)) {
+      return { baseIdentifier: expression.text, calls };
+    }
+    return undefined;
+  }
+}
+
+function isContractFactoryName(value: string): value is ContractFactoryName {
+  return value === "defineContract" || value === "defineContractGroup";
+}
+
+function unwrapExpression(expression: ts.Expression): ts.Expression {
+  let current = expression;
+  while (
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isTypeAssertionExpression(current) ||
+    ts.isNonNullExpression(current) ||
+    ts.isSatisfiesExpression(current)
+  ) {
+    current = current.expression;
+  }
+  return current;
+}

package/src/analysis/layers.ts

@@ -0,0 +1,266 @@
+import path from "node:path";
+import {
+  clientDirPath,
+  directoryPath,
+  normalizePath,
+  type ResolvedBeignetConfig,
+} from "../config.js";
+
+export type SourceLayer =
+  | "app"
+  | "app-context"
+  | "agent-capability"
+  | "client"
+  | "component"
+  | "contract"
+  | "domain"
+  | "feature-helper"
+  | "feature-port"
+  | "infra"
+  | "lib"
+  | "policy"
+  | "port"
+  | "route"
+  | "schema"
+  | "seed"
+  | "server"
+  | "test"
+  | "use-case"
+  | "workflow"
+  | "unknown";
+
+type FeatureLayerConvention = {
+  path: string;
+  layer: SourceLayer;
+};
+
+const canonicalFeatureDirectories = {
+  client: "client",
+  components: "component",
+  domain: "domain",
+  jobs: "workflow",
+  listeners: "workflow",
+  notifications: "workflow",
+  schedules: "workflow",
+  seeds: "seed",
+  tasks: "workflow",
+  tests: "test",
+  uploads: "workflow",
+  "use-cases": "use-case",
+} as const satisfies Record<string, SourceLayer>;
+
+const canonicalFeatureRootFiles = {
+  "agent-capabilities": "agent-capability",
+  contracts: "contract",
+  policy: "policy",
+  ports: "feature-port",
+  routes: "route",
+  schemas: "schema",
+} as const satisfies Record<string, SourceLayer>;
+
+const featureDirectoryAliases = {
+  command: "tasks",
+  commands: "tasks",
+  event: "domain/events",
+  events: "domain/events",
+  job: "jobs",
+  listener: "listeners",
+  notification: "notifications",
+  schedule: "schedules",
+  scheduled: "schedules",
+  task: "tasks",
+  upload: "uploads",
+} as const;
+
+export function classifySourcePath(
+  filePath: string,
+  config: ResolvedBeignetConfig,
+): SourceLayer {
+  const normalizedPath = stripKnownExtension(normalizePath(filePath));
+  const featuresPath = directoryPath(config.paths.features);
+  const portsDir = directoryPath(path.dirname(config.paths.ports));
+
+  if (
+    isTestPath(normalizedPath) ||
+    isUnder(normalizedPath, directoryPath(config.paths.tests))
+  ) {
+    return "test";
+  }
+  if (normalizedPath === stripKnownExtension(config.paths.appContext)) {
+    return "app-context";
+  }
+
+  const featurePath = featureRelativePath(normalizedPath, featuresPath);
+  if (featurePath) {
+    const layerSegment = featurePath.split("/")[1];
+    if (!layerSegment) return "feature-helper";
+    const convention = featureDirectoryConvention(layerSegment);
+    if (convention) return convention.layer;
+    const rootConvention = featureRootFileConvention(layerSegment);
+    if (rootConvention) return rootConvention.layer;
+    if (layerSegment.endsWith("-contracts")) return "contract";
+    return "feature-helper";
+  }
+
+  if (
+    directoryPath(config.paths.contracts) !== featuresPath &&
+    isUnder(normalizedPath, directoryPath(config.paths.contracts))
+  ) {
+    return "contract";
+  }
+  if (
+    directoryPath(config.paths.useCases) !== featuresPath &&
+    isUnder(normalizedPath, directoryPath(config.paths.useCases))
+  ) {
+    return "use-case";
+  }
+  if (
+    directoryPath(config.paths.policies) !== featuresPath &&
+    isUnder(normalizedPath, directoryPath(config.paths.policies))
+  ) {
+    return "policy";
+  }
+
+  if (
+    isUnder(normalizedPath, directoryPath(path.dirname(config.paths.server)))
+  ) {
+    return "server";
+  }
+  if (
+    isUnder(
+      normalizedPath,
+      directoryPath(path.dirname(config.paths.portWiring)),
+    )
+  ) {
+    return "infra";
+  }
+  if (isUnder(normalizedPath, portsDir)) return "port";
+  if (isUnder(normalizedPath, clientDirPath(config))) return "client";
+  if (isUnder(normalizedPath, "components")) return "component";
+  if (isUnder(normalizedPath, legacySharedDomainPath(config))) return "domain";
+  if (isUnder(normalizedPath, "lib")) return "lib";
+  if (
+    isUnder(normalizedPath, directoryPath(path.dirname(config.paths.routes)))
+  ) {
+    return "app";
+  }
+
+  return "unknown";
+}
+
+export function canonicalFeatureLayerPath(
+  filePath: string,
+  config: ResolvedBeignetConfig,
+): string | undefined {
+  const featuresPath = directoryPath(config.paths.features);
+  const relativePath = featureRelativePath(
+    normalizePath(filePath),
+    featuresPath,
+  );
+  if (!relativePath) return undefined;
+
+  const [feature, segment, ...rest] = relativePath.split("/");
+  if (!feature || !segment) return undefined;
+
+  if (isTestSourceFile(segment, rest) && segment !== "tests") {
+    return path.posix.join(
+      featuresPath,
+      feature,
+      "tests",
+      ...(rest.length > 0 ? rest : [segment]),
+    );
+  }
+
+  if (rest.length > 0) {
+    const convention = featureDirectoryConvention(segment);
+    if (!convention || convention.path === segment) return undefined;
+    return path.posix.join(featuresPath, feature, convention.path, ...rest);
+  }
+
+  const extension = path.posix.extname(segment);
+  const stem = extension ? segment.slice(0, -extension.length) : segment;
+  const convention = featureRootFileConvention(stem);
+  if (!convention || convention.path === stem) return undefined;
+  return path.posix.join(
+    featuresPath,
+    feature,
+    `${convention.path}${extension}`,
+  );
+}
+
+function isTestSourceFile(segment: string, rest: string[]): boolean {
+  const fileName = rest.at(-1) ?? segment;
+  return /\.(?:test|spec)\.(?:ts|tsx|mts|cts)$/.test(fileName);
+}
+
+function featureDirectoryConvention(
+  segment: string,
+): FeatureLayerConvention | undefined {
+  const canonical = Object.entries(canonicalFeatureDirectories).find(
+    ([candidate]) =>
+      normalizeLayerSegment(candidate) === normalizeLayerSegment(segment),
+  );
+  if (canonical) return { path: canonical[0], layer: canonical[1] };
+
+  const alias =
+    featureDirectoryAliases[
+      normalizeLayerSegment(segment) as keyof typeof featureDirectoryAliases
+    ];
+  if (!alias) return undefined;
+  return {
+    path: alias,
+    layer:
+      alias === "domain/events"
+        ? "domain"
+        : canonicalFeatureDirectories[
+            alias as keyof typeof canonicalFeatureDirectories
+          ],
+  };
+}
+
+function featureRootFileConvention(
+  segment: string,
+): FeatureLayerConvention | undefined {
+  const canonical = Object.entries(canonicalFeatureRootFiles).find(
+    ([candidate]) =>
+      normalizeLayerSegment(candidate) === normalizeLayerSegment(segment),
+  );
+  return canonical ? { path: canonical[0], layer: canonical[1] } : undefined;
+}
+
+function normalizeLayerSegment(segment: string): string {
+  return segment.replaceAll("-", "").replaceAll("_", "").toLowerCase();
+}
+
+function stripKnownExtension(filePath: string): string {
+  return filePath.replace(/\.(c|m)?tsx?$/, "");
+}
+
+function isTestPath(filePath: string): boolean {
+  return (
+    filePath.includes("/tests/") ||
+    filePath.endsWith(".test") ||
+    filePath.endsWith(".spec")
+  );
+}
+
+function isUnder(filePath: string, directory: string): boolean {
+  const normalizedDir = directoryPath(directory);
+  if (!normalizedDir || normalizedDir === ".") return false;
+  return filePath === normalizedDir || filePath.startsWith(`${normalizedDir}/`);
+}
+
+function featureRelativePath(
+  filePath: string,
+  featuresPath: string,
+): string | undefined {
+  if (!isUnder(filePath, featuresPath)) return undefined;
+  return filePath.slice(`${directoryPath(featuresPath)}/`.length);
+}
+
+function legacySharedDomainPath(config: ResolvedBeignetConfig): string {
+  const featuresDir = directoryPath(config.paths.features);
+  const featuresParent = directoryPath(path.dirname(featuresDir));
+  if (!featuresParent || featuresParent === ".") return "domain";
+  return path.join(featuresParent, "domain");
+}