@akanjs/devkit 2.3.9-rc.3 → 2.3.9-rc.5

package/akanContext.ts

@@ -713,8 +713,14 @@ export class AkanContextAnalyzer {
     };
   }
 
-  static findModules(context: AkanWorkspaceContext, moduleName?: string | null) {
-    const modules = [...context.apps, ...context.libs].flatMap((sys) => sys.modules);
+  static findModules(
+    context: AkanWorkspaceContext,
+    moduleName?: string | null,
+    { app = null }: { app?: string | null } = {},
+  ) {
+    const modules = [...context.apps, ...context.libs]
+      .filter((sys) => !app || sys.name === app)
+      .flatMap((sys) => sys.modules);
     return moduleName
       ? modules.filter((module) => module.name === moduleName || module.folderName === moduleName)
       : modules;

package/devkitUtils.test.ts

@@ -269,11 +269,11 @@ describe("getModelFileData", () => {
         ].join("\n"),
       );
       await write(
-        path.join(root, "apps/demo/lib/post/post.Unit.tsx"),
+        path.join(root, "apps/demo/lib/post/Post.Unit.tsx"),
         "export default function Unit() { return null; }\n",
       );
       await write(
-        path.join(root, "apps/demo/lib/post/post.View.tsx"),
+        path.join(root, "apps/demo/lib/post/Post.View.tsx"),
         "export default function View() { return null; }\n",
       );
 

package/executors.ts

@@ -626,14 +626,14 @@ export class Executor {
       overwrite?: boolean;
     },
     dict: { [key: string]: string } = {},
-    options: { [key: string]: any } = {},
+    options: { [key: string]: unknown } = {},
   ): Promise<FileContent | null> {
     if (targetPath.endsWith(".ts") || targetPath.endsWith(".tsx")) {
       const getContent = (await import(templatePath)) as {
         default: (
           scanInfo: AppInfo | LibInfo | null,
           dict: { [key: string]: string },
-          options?: { [key: string]: any },
+          options?: { [key: string]: unknown },
         ) => Promise<string | null | { filename: string; content: string }>;
       };
       const result = await getContent.default(scanInfo ?? null, dict, options);
@@ -686,7 +686,7 @@ export class Executor {
     template: string;
     scanInfo?: AppInfo | LibInfo | null;
     dict?: { [key: string]: string };
-    options?: { [key: string]: any };
+    options?: { [key: string]: unknown };
     overwrite?: boolean;
   }): Promise<FileContent[]> {
     const templateRoot = await this.#resolveTemplateRoot();
@@ -752,7 +752,7 @@ export class Executor {
     basePath: string;
     template: string;
     dict?: { [key: string]: string };
-    options?: { [key: string]: any };
+    options?: { [key: string]: unknown };
     overwrite?: boolean;
   }): Promise<FileContent[]> {
     const dict = {
@@ -827,10 +827,10 @@ export class Executor {
     filePath: string,
     { fix = false, dryRun = false }: { fix?: boolean; dryRun?: boolean } = {},
   ): Promise<{
-    results: any[]; // ESLint.LintResult[];
+    results: unknown[]; // ESLint.LintResult[];
     message: string;
-    errors: any[]; // ESLintLinter.LintMessage[];
-    warnings: any[]; // ESLintLinter.LintMessage[];
+    errors: unknown[]; // ESLintLinter.LintMessage[];
+    warnings: unknown[]; // ESLintLinter.LintMessage[];
   }> {
     const path = this.getPath(filePath);
     const linter = this.getLinter();
@@ -1225,40 +1225,44 @@ export class SysExecutor extends Executor {
   async getViewComponents() {
     const viewComponents = (await this.readdir("lib"))
       .filter((name) => !name.startsWith("_") && !name.startsWith("__") && !name.endsWith(".ts"))
-      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${name}.View.tsx`).exists());
+      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${capitalize(name)}.View.tsx`).exists());
     return viewComponents;
   }
 
   async getUnitComponents() {
     const unitComponents = (await this.readdir("lib"))
       .filter((name) => !name.startsWith("_") && !name.startsWith("__") && !name.endsWith(".ts"))
-      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${name}.Unit.tsx`).exists());
+      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${capitalize(name)}.Unit.tsx`).exists());
     return unitComponents;
   }
   async getTemplateComponents() {
     const templateComponents = (await this.readdir("lib"))
       .filter((name) => !name.startsWith("_") && !name.startsWith("__") && !name.endsWith(".ts"))
-      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${name}.Template.tsx`).exists());
+      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${capitalize(name)}.Template.tsx`).exists());
     return templateComponents;
   }
 
   async getViewsSourceCode() {
     const viewComponents = await this.getViewComponents();
     return Promise.all(
-      viewComponents.map((viewComponent) => this.getLocalFile(`lib/${viewComponent}/${viewComponent}.View.tsx`)),
+      viewComponents.map((viewComponent) =>
+        this.getLocalFile(`lib/${viewComponent}/${capitalize(viewComponent)}.View.tsx`),
+      ),
     );
   }
   async getUnitsSourceCode() {
     const unitComponents = await this.getUnitComponents();
     return Promise.all(
-      unitComponents.map((unitComponent) => this.getLocalFile(`lib/${unitComponent}/${unitComponent}.Unit.tsx`)),
+      unitComponents.map((unitComponent) =>
+        this.getLocalFile(`lib/${unitComponent}/${capitalize(unitComponent)}.Unit.tsx`),
+      ),
     );
   }
   async getTemplatesSourceCode() {
     const templateComponents = await this.getTemplateComponents();
     return Promise.all(
       templateComponents.map((templateComponent) =>
-        this.getLocalFile(`lib/${templateComponent}/${templateComponent}.Template.tsx`),
+        this.getLocalFile(`lib/${templateComponent}/${capitalize(templateComponent)}.Template.tsx`),
       ),
     );
   }

package/getModelFileData.ts

@@ -1,3 +1,5 @@
+import { capitalize } from "akanjs/common";
+
 interface ModelFileData {
   moduleType: "lib" | "app";
   moduleName: string;
@@ -16,9 +18,10 @@ interface ModelFileData {
 export const getModelFileData = async (modulePath: string, modelName: string): Promise<ModelFileData> => {
   const moduleType = modulePath.startsWith("apps") ? "app" : "lib";
   const moduleName = modulePath.split("/")[1] ?? "";
+  const modelComponentName = capitalize(modelName);
   const constantFilePath = `${modulePath}/lib/${modelName}/${modelName}.constant.ts`;
-  const unitFilePath = `${modulePath}/lib/${modelName}/${modelName}.Unit.tsx`;
-  const viewFilePath = `${modulePath}/lib/${modelName}/${modelName}.View.tsx`;
+  const unitFilePath = `${modulePath}/lib/${modelName}/${modelComponentName}.Unit.tsx`;
+  const viewFilePath = `${modulePath}/lib/${modelName}/${modelComponentName}.View.tsx`;
   const [constantFileStr, unitFileStr, viewFileStr] = await Promise.all([
     Bun.file(constantFilePath).text(),
     Bun.file(unitFilePath).text(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.9-rc.3",
+  "version": "2.3.9-rc.5",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.9-rc.3",
+    "akanjs": "2.3.9-rc.5",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/workflow/artifacts.ts

@@ -0,0 +1,415 @@
+import type { Workspace } from "../commandDecorators";
+import type {
+  GeneratedSyncState,
+  PrimitiveChangedFile,
+  PrimitiveGeneratedFile,
+  RepairAction,
+  RepairReport,
+  WorkflowApplyCommand,
+  WorkflowApplyReport,
+  WorkflowDiagnostic,
+  WorkflowFailureScope,
+  WorkflowKnownBlocker,
+  WorkflowPlan,
+  WorkflowRunArtifact,
+  WorkflowRunSource,
+  WorkflowValidationCommandResult,
+  WorkflowValidationRunReport,
+  WorkflowValidationStatus,
+} from "./types";
+import { commandStatus, jsonText, uniqueBy, workflowStatus } from "./utils";
+
+export const createWorkflowApplyReport = ({
+  workflow,
+  mode,
+  changedFiles = [],
+  generatedFiles = [],
+  appliedCommands = [],
+  recommendedValidationCommands,
+  commands = [],
+  diagnostics = [],
+  recommendations = [],
+  nextActions = [],
+  plan,
+}: Omit<
+  WorkflowApplyReport,
+  | "schemaVersion"
+  | "runId"
+  | "applyReportPath"
+  | "validationTarget"
+  | "status"
+  | "appliedCommands"
+  | "recommendedValidationCommands"
+  | "commands"
+  | "recommendations"
+> & {
+  appliedCommands?: WorkflowApplyCommand[];
+  recommendedValidationCommands?: WorkflowApplyCommand[];
+  commands?: WorkflowApplyCommand[];
+  recommendations?: WorkflowApplyReport["recommendations"];
+}): WorkflowApplyReport => {
+  const validationCommands = recommendedValidationCommands ?? commands;
+  return {
+    schemaVersion: 1,
+    workflow,
+    mode,
+    status: workflowStatus(diagnostics),
+    changedFiles: uniqueBy(changedFiles, (file) => `${file.action}:${file.path}:${file.reason}`),
+    generatedFiles: uniqueBy(generatedFiles, (file) => `${file.action}:${file.path}:${file.reason}`),
+    appliedCommands: uniqueBy(appliedCommands, (command) => command.command),
+    recommendedValidationCommands: uniqueBy(validationCommands, (command) => command.command),
+    commands: uniqueBy(validationCommands, (command) => command.command),
+    diagnostics,
+    recommendations: uniqueBy(recommendations, (recommendation) => `${recommendation.kind}:${recommendation.code}`),
+    nextActions: uniqueBy(nextActions, (action) => action.command),
+    plan,
+  };
+};
+
+export const resolveWorkflowCommand = (command: string, plan: WorkflowPlan) => {
+  const target = typeof plan.inputs.app === "string" ? plan.inputs.app : "<app-or-lib>";
+  return command
+    .replaceAll("<app-or-lib-or-pkg>", target)
+    .replaceAll("<app-or-lib>", target)
+    .replaceAll("<app-name>", target);
+};
+
+export const workflowCommandsForPlan = (plan: WorkflowPlan) =>
+  plan.validation.map((validation) => ({
+    command: resolveWorkflowCommand(validation.command, plan),
+    reason: validation.reason,
+    kind: validation.kind,
+  })) satisfies WorkflowApplyCommand[];
+
+export const workflowRunsDir = ".akan/workflows/runs";
+
+export const createWorkflowRunId = (prefix = "run") =>
+  `${prefix}-${new Date()
+    .toISOString()
+    .replace(/[-:.TZ]/g, "")
+    .slice(0, 14)}-${Math.random().toString(36).slice(2, 8)}`;
+
+const getRunId = (artifact: WorkflowRunArtifact) => {
+  if ("runId" in artifact && artifact.runId) return artifact.runId;
+  return createWorkflowRunId("mode" in artifact ? artifact.mode : artifact.kind);
+};
+
+export const workflowRunArtifactPath = (runId: string) => `${workflowRunsDir}/${runId}.json`;
+
+const withWorkflowRunMetadata = (
+  artifact: WorkflowRunArtifact,
+  runId: string,
+  artifactPath: string,
+): WorkflowRunArtifact => {
+  if ("mode" in artifact && (artifact.mode === "apply" || artifact.mode === "dry-run")) {
+    return { ...artifact, runId, applyReportPath: artifactPath, validationTarget: artifactPath };
+  }
+  if ("kind" in artifact) return { ...artifact, runId, repairReportPath: artifactPath };
+  return artifact;
+};
+
+export const writeWorkflowRunArtifact = async (workspace: Workspace, artifact: WorkflowRunArtifact) => {
+  const runId = getRunId(artifact);
+  const artifactPath = workflowRunArtifactPath(runId);
+  const artifactWithMetadata = withWorkflowRunMetadata(artifact, runId, artifactPath);
+  await workspace.writeFile(artifactPath, jsonText(artifactWithMetadata), { silent: true });
+  return { runId, path: artifactPath, artifact: artifactWithMetadata };
+};
+
+export const workflowSyncDir = ".akan/workflows/sync";
+
+const syncStateSlug = (target: string) =>
+  target
+    .trim()
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+
+export const workflowSyncStatePath = (target: string) => `${workflowSyncDir}/${syncStateSlug(target) || "target"}.json`;
+
+export const generatedFilePathsForTarget = (targetRoot: string, reason = "Generated files were refreshed by sync.") =>
+  [
+    { path: `${targetRoot}/lib/cnst.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/dict.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/option.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/index.ts`, action: "sync", reason },
+  ] satisfies PrimitiveGeneratedFile[];
+
+export const writeGeneratedSyncState = async (workspace: Workspace, state: GeneratedSyncState) => {
+  const statePath = workflowSyncStatePath(state.target);
+  await workspace.writeFile(statePath, jsonText(state), { silent: true });
+  return statePath;
+};
+
+export const readWorkflowRunArtifact = async (workspace: Workspace, runId: string) => {
+  const artifactPath = workflowRunArtifactPath(runId);
+  if (!(await workspace.exists(artifactPath))) throw new Error(`Workflow run artifact does not exist: ${artifactPath}`);
+  return (await workspace.readJson(artifactPath)) as WorkflowRunArtifact;
+};
+
+export type WorkflowValidationCommandExecutor = (
+  command: WorkflowApplyCommand,
+) => Promise<WorkflowValidationCommandResult>;
+
+const failedCommandScopes = (commands: readonly WorkflowValidationCommandResult[]) =>
+  commands.filter((command) => command.status === "failed").map((command) => command.failureScope ?? "unknown");
+
+const errorDiagnosticScopes = (diagnostics: readonly WorkflowDiagnostic[]) =>
+  diagnostics
+    .filter((diagnostic) => diagnostic.severity === "error")
+    .map(
+      (diagnostic) =>
+        diagnostic.failureScope ??
+        (diagnostic.scope === "baseline"
+          ? "workspace-config"
+          : diagnostic.scope === "workflow"
+            ? "source-change"
+            : "unknown"),
+    );
+
+const hasScopeFailure = (
+  scopes: readonly WorkflowFailureScope[],
+  scope: WorkflowFailureScope,
+  diagnostics: readonly WorkflowDiagnostic[] = [],
+) =>
+  scopes.includes(scope) ||
+  diagnostics.some((diagnostic) => diagnostic.severity === "error" && diagnostic.failureScope === scope);
+
+const statusForScope = (
+  commands: readonly WorkflowValidationCommandResult[],
+  diagnostics: readonly WorkflowDiagnostic[],
+  scopes: readonly WorkflowFailureScope[],
+  expectedScope: WorkflowFailureScope,
+): WorkflowValidationStatus => {
+  const hasCommands = commands.length > 0 || diagnostics.length > 0;
+  if (!hasCommands) return "unknown";
+  return hasScopeFailure(scopes, expectedScope, diagnostics) ? "failed" : "passed";
+};
+
+const statusForValidationKind = (
+  commands: readonly WorkflowValidationCommandResult[],
+  kind: WorkflowValidationCommandResult["kind"],
+): WorkflowValidationStatus => {
+  const matching = commands.filter((command) => command.kind === kind);
+  if (matching.length === 0) return "unknown";
+  return matching.some((command) => command.status === "failed") ? "failed" : "passed";
+};
+
+const createKnownBlockers = (
+  commands: readonly WorkflowValidationCommandResult[],
+  diagnostics: readonly WorkflowDiagnostic[],
+): WorkflowKnownBlocker[] => {
+  const commandBlockers = commands
+    .filter(
+      (command) =>
+        command.status === "failed" &&
+        (command.failureScope === "workspace-config" || command.failureScope === "environment"),
+    )
+    .map((command) => ({
+      code: `workflow-validation-${command.failureScope}`,
+      message: `${command.failureScope === "environment" ? "Environment" : "Workspace configuration"} blocker: ${command.command}`,
+      failureScope: command.failureScope ?? "unknown",
+      command: command.command,
+      kind: command.kind,
+      count: 1,
+    }));
+  const diagnosticBlockers = diagnostics
+    .filter(
+      (diagnostic) =>
+        diagnostic.severity === "error" &&
+        (diagnostic.failureScope === "workspace-config" ||
+          diagnostic.failureScope === "environment" ||
+          diagnostic.scope === "baseline"),
+    )
+    .map((diagnostic) => ({
+      code: diagnostic.code,
+      message: diagnostic.message,
+      failureScope: diagnostic.failureScope ?? ("workspace-config" as const),
+      command: diagnostic.command,
+      kind: diagnostic.kind,
+      count: 1,
+    }));
+  const grouped = new Map<string, WorkflowKnownBlocker>();
+  for (const blocker of [...commandBlockers, ...diagnosticBlockers]) {
+    const key = `${blocker.failureScope}:${blocker.code}:${blocker.command ?? ""}:${blocker.message}`;
+    const existing = grouped.get(key);
+    if (existing) existing.count += blocker.count;
+    else grouped.set(key, blocker);
+  }
+  return [...grouped.values()];
+};
+
+const createValidationStatuses = (
+  commands: readonly WorkflowValidationCommandResult[],
+  diagnostics: readonly WorkflowDiagnostic[],
+) => {
+  const scopes = [...failedCommandScopes(commands), ...errorDiagnosticScopes(diagnostics)];
+  const sourceStatus = statusForScope(commands, diagnostics, scopes, "source-change");
+  const workspaceStatus =
+    hasScopeFailure(scopes, "workspace-config", diagnostics) || hasScopeFailure(scopes, "environment", diagnostics)
+      ? "failed"
+      : commands.length || diagnostics.length
+        ? "passed"
+        : "unknown";
+  const overallStatus = hasScopeFailure(scopes, "source-change", diagnostics)
+    ? "failed"
+    : hasScopeFailure(scopes, "workspace-config", diagnostics)
+      ? "blocked-by-workspace-config"
+      : hasScopeFailure(scopes, "environment", diagnostics)
+        ? "blocked-by-environment"
+        : workflowStatus(diagnostics) === "failed" || commandStatus(commands) === "failed"
+          ? "failed"
+          : "passed";
+  return {
+    sourceStatus,
+    workspaceStatus,
+    overallStatus,
+    summary: {
+      sourceChange: sourceStatus,
+      generatedSync: statusForValidationKind(commands, "sync"),
+      workspaceConfig: statusForScope(commands, diagnostics, scopes, "workspace-config"),
+      environment: statusForScope(commands, diagnostics, scopes, "environment"),
+    },
+  };
+};
+
+export const createWorkflowValidationRunReport = async ({
+  runId = createWorkflowRunId("validation"),
+  workflow,
+  source,
+  plan,
+  commands,
+  execute,
+  diagnostics = [],
+  baselineDiagnostics = [],
+  workflowDiagnostics = [],
+  repairActions = [],
+}: {
+  runId?: string;
+  workflow: string;
+  source: WorkflowRunSource;
+  plan?: WorkflowPlan;
+  commands: WorkflowApplyCommand[];
+  execute: WorkflowValidationCommandExecutor;
+  diagnostics?: WorkflowDiagnostic[];
+  baselineDiagnostics?: WorkflowDiagnostic[];
+  workflowDiagnostics?: WorkflowDiagnostic[];
+  repairActions?: RepairAction[];
+}): Promise<WorkflowValidationRunReport> => {
+  const results: WorkflowValidationCommandResult[] = [];
+  for (const command of commands) {
+    results.push(await execute(command));
+  }
+  const commandDiagnostics = results.flatMap((result) =>
+    result.status === "failed"
+      ? [
+          {
+            severity: "error" as const,
+            code: "workflow-validation-command-failed",
+            message: `Validation command failed: ${result.command}`,
+            command: result.command,
+            kind: result.kind,
+            failureScope: result.failureScope,
+          },
+        ]
+      : [],
+  );
+  const reportDiagnostics = [...diagnostics, ...commandDiagnostics];
+  const scopedDiagnostics = [...reportDiagnostics, ...baselineDiagnostics, ...workflowDiagnostics];
+  const statuses = createValidationStatuses(results, scopedDiagnostics);
+  return {
+    schemaVersion: 1,
+    runId,
+    workflow,
+    mode: "validate",
+    source,
+    status: statuses.overallStatus === "passed" ? "passed" : "failed",
+    ...statuses,
+    knownBlockers: createKnownBlockers(results, scopedDiagnostics),
+    commands: results,
+    diagnostics: reportDiagnostics,
+    baselineDiagnostics,
+    workflowDiagnostics,
+    repairActions: uniqueBy(repairActions, (action) => action.command),
+    nextActions: results
+      .filter((result) => result.status === "failed")
+      .map((result) => ({ command: result.command, reason: "Re-run this validation command after repair." })),
+    plan,
+  };
+};
+
+export const createDryRunWorkflowApplyReport = (plan: WorkflowPlan) => {
+  const changedFiles: PrimitiveChangedFile[] = plan.predictedChanges.flatMap((change) => {
+    if (change.action !== "create" && change.action !== "modify") return [];
+    return [
+      {
+        path: change.target,
+        action: change.action,
+        reason: change.reason,
+      },
+    ];
+  });
+  const generatedFiles: PrimitiveGeneratedFile[] = plan.predictedChanges.flatMap((change) => {
+    if (change.action !== "sync") return [];
+    return [
+      {
+        path: change.target,
+        action: "sync",
+        reason: change.reason,
+      },
+    ];
+  });
+  const diagnostics = [...plan.diagnostics];
+  return createWorkflowApplyReport({
+    workflow: plan.workflow,
+    mode: "dry-run",
+    changedFiles,
+    generatedFiles,
+    commands: workflowCommandsForPlan(plan),
+    diagnostics,
+    recommendations: plan.recommendations,
+    nextActions: workflowCommandsForPlan(plan),
+    plan,
+  });
+};
+
+export const createRepairReport = ({
+  command,
+  kind,
+  target = null,
+  diagnostics = [],
+  repairActions = [],
+  nextActions = [],
+  commands = [],
+  generatedFiles = [],
+  syncedAt,
+}: Omit<
+  RepairReport,
+  | "schemaVersion"
+  | "runId"
+  | "repairReportPath"
+  | "status"
+  | "target"
+  | "diagnostics"
+  | "repairActions"
+  | "nextActions"
+  | "commands"
+> &
+  Partial<
+    Pick<
+      RepairReport,
+      "target" | "diagnostics" | "repairActions" | "nextActions" | "commands" | "generatedFiles" | "syncedAt"
+    >
+  >): RepairReport => ({
+  schemaVersion: 1,
+  command,
+  kind,
+  target,
+  status: workflowStatus(diagnostics) === "failed" || commandStatus(commands) === "failed" ? "failed" : "passed",
+  diagnostics,
+  repairActions: uniqueBy(repairActions, (action) => action.command),
+  nextActions: uniqueBy(nextActions, (action) => action.command),
+  commands,
+  generatedFiles,
+  ...(syncedAt ? { syncedAt } : {}),
+});