@beignet/cli 0.0.52 → 0.0.53

package/skills/app-structure/SKILL.md

@@ -77,6 +77,15 @@ beignet db migrate
 beignet db status
 ```
 
+## Encryption keys
+
+`beignet encryption key` prints a fresh key for `@beignet/core/encryption`;
+`--json` returns `schemaVersion` and `key`. It does not read or overwrite env
+files. Keep the output out of shared logs and wire the persistent key through
+server env config and `infra/port-wiring.ts`. Retain keys needed by existing
+records and backups during rotation. The starter does not configure encryption
+until the app needs it; no encryption generator or provider preset is required.
+
 ## Explicit Registration
 
 Hand-written files do not run until registered:
@@ -174,6 +183,39 @@ root at `src/client/index.ts`. Other registries and app-bound builders are not
 relocated implicitly; override each path the app has moved, such as
 `listeners`, `schedules`, `tasks`, `outbox`, and their matching builder paths.
 
+## Workspace Source Packages
+
+An app may set `workspace.packages` to explicit relative source-package
+paths, including transitive dependencies. Each included package must have a
+unique manifest name, belong to the app's declared dependency graph, and use a
+separate root. Read the package's own Beignet config and TypeScript config
+before changing its files. Package exports must resolve to source; do not guess
+source from `dist` or declaration files.
+
+Lint follows imports and reexports across these packages using each owner's
+layers. Relative imports, TypeScript aliases, and `package.json#imports` aliases
+that resolve outside the configured source roots also require the owning source
+package in `workspace.packages`. Aliases to installed external dependencies remain
+external imports.
+Shared feature names in map/explain are qualified as
+`@scope/package:feature`, and source evidence remains app-relative, including
+`../`. Routes/doctor follow explicit server route composition and report
+unresolved workspace registration instead of executing it. Trace the exported
+server or the value returned by the exported Next.js server loader; unused
+factory calls do not establish registration. Verified per-file Next.js handlers
+do not require central registration. AppPorts and initialPorts may be reexported
+through source entrypoints, including wiring aliases used by inferred AppPorts.
+Import-then-export barrels and type-only port exports are supported. Match
+contracts by their resolved declaration, including loader-local aliases, rather
+than assuming export names are unique across packages.
+
+Keep startup, lifecycle provider registration, env, database commands, and
+operational registries app-owned. Those doctor checks still use app conventions;
+a worker-only package can run lint without pretending to expose an HTTP server.
+Generators and doctor repairs stay within the selected app. Never put a sibling
+package path into `paths.*` to make a generator write there. See the CLI README's
+workspace source packages section for the supported scope and fixture.
+
 ## Lint And Doctor
 
 Start unfamiliar app work with `beignet map`. Its human output summarizes each

package/src/analysis/layers.ts

@@ -7,6 +7,15 @@ import {
 } from "../config.js";
 import { isAppTestFile } from "../test-discovery.js";
 import { stripSourceFileExtension } from "./source-files.js";
+import { type AnalysisWorkspace, projectSource } from "./workspace.js";
+
+export function classifyWorkspaceSourcePath(
+  file: string,
+  workspace: AnalysisWorkspace,
+): SourceLayer {
+  const source = projectSource(workspace, file);
+  return classifySourcePath(source.file, source.project.config);
+}
 
 export type SourceLayer =
   | "app"

package/src/analysis/port-wiring.ts

@@ -3,7 +3,15 @@ import path from "node:path";
 import ts from "typescript";
 import type { ResolvedBeignetConfig } from "../config.js";
 import { sourceFileScriptKind } from "./source-files.js";
-import type { AnalysisWorkspace } from "./workspace.js";
+import {
+  createSourceIndex,
+  type ResolvedSourceReference,
+  type SourceIndex,
+} from "./source-index.js";
+import {
+  type AnalysisWorkspace,
+  createAnalysisWorkspace,
+} from "./workspace.js";
 
 type PortAnalysisWorkspace = Pick<
   AnalysisWorkspace,
@@ -14,6 +22,7 @@ export type PortWiringAnalysis = {
   portsFileExists: boolean;
   portWiringFileExists: boolean;
   properties: Map<string, ts.PropertySignature>;
+  propertyFiles: Map<string, string>;
   declared: Set<string>;
   bound: Set<string>;
   deferred: Set<string>;
@@ -24,6 +33,7 @@ export type PortWiringAnalysis = {
 
 export async function analyzePortWiring(
   workspace: PortAnalysisWorkspace,
+  sourceIndex?: SourceIndex,
 ): Promise<PortWiringAnalysis> {
   const result: PortWiringAnalysis = {
     portsFileExists: workspace.fileSet.has(workspace.config.paths.ports),
@@ -31,6 +41,7 @@ export async function analyzePortWiring(
       workspace.config.paths.portWiring,
     ),
     properties: new Map(),
+    propertyFiles: new Map(),
     declared: new Set(),
     bound: new Set(),
     deferred: new Set(),
@@ -40,20 +51,31 @@ export async function analyzePortWiring(
   };
 
   let inferredAppPortsName: string | undefined;
+  let inferredAppPortsReference: ResolvedSourceReference | undefined;
   if (result.portsFileExists) {
-    const sourceFile = await workspace.readSourceFile(
+    const reference = await sourceIndex?.resolveExport(
       workspace.config.paths.ports,
+      "AppPorts",
     );
+    const portsFile = reference?.file ?? workspace.config.paths.ports;
+    const portsName = reference?.exportName ?? "AppPorts";
+    const sourceFile = await workspace.readSourceFile(portsFile);
     const declarations = collectTypeDeclarations(sourceFile);
-    inferredAppPortsName = inferredTypeQueryName("AppPorts", declarations);
+    inferredAppPortsName = inferredTypeQueryName(portsName, declarations);
+    if (inferredAppPortsName)
+      inferredAppPortsReference = await sourceIndex?.resolveName(
+        portsFile,
+        inferredAppPortsName,
+      );
     const collection = inferredAppPortsName
       ? { properties: [], indeterminate: false }
-      : collectNamedTypeProperties("AppPorts", declarations, true);
+      : collectNamedTypeProperties(portsName, declarations, !sourceIndex);
     result.declarationIndeterminate = collection.indeterminate;
     for (const property of collection.properties) {
       const name = propertyName(property.name);
       if (name && !result.properties.has(name)) {
         result.properties.set(name, property);
+        result.propertyFiles.set(name, portsFile);
         result.declared.add(name);
       }
     }
@@ -63,12 +85,27 @@ export async function analyzePortWiring(
     if (inferredAppPortsName) result.declarationIndeterminate = true;
     return result;
   }
-  const sourceFile = await workspace.readSourceFile(
+  const wiringReference = await sourceIndex?.resolveExport(
     workspace.config.paths.portWiring,
+    "initialPorts",
+  );
+  const sourceFile = await workspace.readSourceFile(
+    wiringReference?.file ?? workspace.config.paths.portWiring,
   );
   const values = collectVariableInitializers(sourceFile);
-  const definitions = portDefinitionCalls(sourceFile);
-  if (definitions.indeterminate) result.indeterminate = true;
+  const definitions = portDefinitionCalls(
+    sourceFile,
+    wiringReference?.declaration &&
+      ts.isVariableDeclaration(wiringReference.declaration) &&
+      ts.isIdentifier(wiringReference.declaration.name)
+      ? wiringReference.declaration.name.text
+      : wiringReference?.exportName,
+  );
+  if (
+    definitions.indeterminate ||
+    (sourceIndex && definitions.calls.length === 0)
+  )
+    result.indeterminate = true;
 
   for (const call of definitions.calls) {
     const objectArgument = call.arguments
@@ -124,7 +161,13 @@ export async function analyzePortWiring(
   if (inferredAppPortsName) {
     if (
       !definitions.indeterminate &&
-      definitions.name === inferredAppPortsName
+      (sourceIndex
+        ? Boolean(
+            inferredAppPortsReference?.declaration &&
+              inferredAppPortsReference.declaration ===
+                wiringReference?.declaration,
+          )
+        : definitions.name === inferredAppPortsName)
     ) {
       result.appPortsInferredFromWiring = true;
       for (const name of result.bound) result.declared.add(name);
@@ -137,7 +180,10 @@ export async function analyzePortWiring(
   return result;
 }
 
-function portDefinitionCalls(sourceFile: ts.SourceFile): {
+function portDefinitionCalls(
+  sourceFile: ts.SourceFile,
+  preferredName?: string,
+): {
   calls: ts.CallExpression[];
   name?: string;
   indeterminate: boolean;
@@ -172,8 +218,12 @@ function portDefinitionCalls(sourceFile: ts.SourceFile): {
   }
 
   const canonical = candidates.filter(
-    (candidate) => candidate.name === "initialPorts" && candidate.exported,
+    (candidate) =>
+      candidate.name === (preferredName ?? "initialPorts") &&
+      candidate.exported,
   );
+  if (preferredName && canonical.length === 0)
+    return { calls: [], indeterminate: true };
   const exported = candidates.filter((candidate) => candidate.exported);
   const selected =
     canonical.length > 0
@@ -230,6 +280,12 @@ export async function analyzePortWiringFiles(options: {
   files: readonly string[];
   config: ResolvedBeignetConfig;
 }): Promise<PortWiringAnalysis> {
+  if (options.config.workspace.packages.length > 0) {
+    const workspace = await createAnalysisWorkspace(options.targetDir, {
+      config: options.config,
+    });
+    return analyzePortWiring(workspace, createSourceIndex(workspace));
+  }
   const sourceFiles = new Map<string, ts.SourceFile>();
   return analyzePortWiring({
     config: options.config,

package/src/analysis/source-index.ts

@@ -53,6 +53,12 @@ export type SourceIndex = {
   resolveExpression(
     file: string,
     expression: ts.Expression,
+    locals?: ReadonlyMap<string, ts.Declaration>,
+  ): Promise<ResolvedSourceReference | undefined>;
+  resolveValue(
+    file: string,
+    expression: ts.Expression,
+    locals?: ReadonlyMap<string, ts.Declaration>,
   ): Promise<ResolvedSourceReference | undefined>;
   resolveExport(
     file: string,
@@ -131,7 +137,6 @@ export function createSourceIndex(workspace: AnalysisWorkspace): SourceIndex {
             ts.isNamedExports(statement.exportClause)
           ) {
             for (const element of statement.exportClause.elements) {
-              if (statement.isTypeOnly || element.isTypeOnly) continue;
               index.localExports.set(
                 element.name.text,
                 element.propertyName?.text ?? element.name.text,
@@ -208,6 +213,9 @@ export function createSourceIndex(workspace: AnalysisWorkspace): SourceIndex {
     if (localDeclaration) {
       return { file, exportName, declaration: localDeclaration };
     }
+    const imported = localName ? index.imports.get(localName) : undefined;
+    if (imported?.kind === "named")
+      return resolveExport(imported.file, imported.exportName, visited);
 
     const reexport = index.reexports.get(exportName);
     if (reexport) {
@@ -227,7 +235,7 @@ export function createSourceIndex(workspace: AnalysisWorkspace): SourceIndex {
     return undefined;
   };
 
-  return {
+  const sourceIndex: SourceIndex = {
     async resolveName(file, name) {
       const index = await readIndex(file);
       const local = index.locals.get(name);
@@ -244,11 +252,12 @@ export function createSourceIndex(workspace: AnalysisWorkspace): SourceIndex {
         }
       );
     },
-    async resolveExpression(file, rawExpression) {
+    async resolveExpression(file, rawExpression, locals) {
       const expression = unwrapExpression(rawExpression);
       const index = await readIndex(file);
       if (ts.isIdentifier(expression)) {
-        const local = index.declarations.get(expression.text);
+        const local =
+          locals?.get(expression.text) ?? index.locals.get(expression.text);
         if (local) {
           return { file, exportName: expression.text, declaration: local };
         }
@@ -267,6 +276,11 @@ export function createSourceIndex(workspace: AnalysisWorkspace): SourceIndex {
         ts.isPropertyAccessExpression(expression) &&
         ts.isIdentifier(expression.expression)
       ) {
+        if (
+          locals?.has(expression.expression.text) ||
+          index.locals.has(expression.expression.text)
+        )
+          return undefined;
         const binding = index.imports.get(expression.expression.text);
         if (binding?.kind !== "namespace") return undefined;
         return (
@@ -279,6 +293,43 @@ export function createSourceIndex(workspace: AnalysisWorkspace): SourceIndex {
 
       return undefined;
     },
+    async resolveValue(file, expression, locals) {
+      const visited = new Set<ts.Declaration>();
+      async function follow(
+        file: string,
+        rawExpression: ts.Expression,
+        locals?: ReadonlyMap<string, ts.Declaration>,
+      ): Promise<ResolvedSourceReference | undefined> {
+        const expression = unwrapExpression(rawExpression);
+        const reference = await sourceIndex.resolveExpression(
+          file,
+          expression,
+          locals,
+        );
+        const declaration = reference?.declaration;
+        if (!reference || !declaration || visited.has(declaration))
+          return undefined;
+        visited.add(declaration);
+        if (!ts.isVariableDeclaration(declaration) || !declaration.initializer)
+          return reference;
+        if (
+          !ts.isVariableDeclarationList(declaration.parent) ||
+          !(declaration.parent.flags & ts.NodeFlags.Const)
+        )
+          return undefined;
+        const initializer = unwrapExpression(declaration.initializer);
+        if (
+          !ts.isIdentifier(initializer) &&
+          !ts.isPropertyAccessExpression(initializer)
+        )
+          return reference;
+        const local =
+          ts.isIdentifier(expression) &&
+          locals?.get(expression.text) === declaration;
+        return follow(reference.file, initializer, local ? locals : undefined);
+      }
+      return follow(file, expression, locals);
+    },
     resolveExport(file, exportName) {
       return resolveExport(file, exportName);
     },
@@ -295,6 +346,7 @@ export function createSourceIndex(workspace: AnalysisWorkspace): SourceIndex {
       };
     },
   };
+  return sourceIndex;
 }
 
 export function exportedVariableDeclarations(