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

package/workflow/source.ts

@@ -0,0 +1,224 @@
+import type { Sys } from "../commandDecorators";
+import { generatedFilePathsForTarget } from "./artifacts";
+import { createPrimitiveWriteReport } from "./primitive";
+import type {
+  PrimitiveChangedFile,
+  PrimitiveFileMap,
+  PrimitiveGeneratedFile,
+  PrimitiveNextAction,
+  PrimitiveValidationCommand,
+  WorkflowDiagnostic,
+} from "./types";
+
+export const getSysRoot = (sys: Sys) => `${sys.type}s/${sys.name}`;
+
+export const sourceFile = (sys: Sys, path: string, action: PrimitiveChangedFile["action"], reason: string) => ({
+  path: `${getSysRoot(sys)}/${path}`,
+  action,
+  reason,
+});
+
+export const generatedFilesForSync = (sys: Sys, reason = "Generated files may change after sync.") =>
+  generatedFilePathsForTarget(getSysRoot(sys), reason);
+
+export const validationCommandsForTarget = (target: string) =>
+  [
+    { command: `akan sync ${target}`, reason: "Refresh generated Akan files from source conventions." },
+    { command: `akan lint ${target}`, reason: "Validate formatting, imports, and static lint rules." },
+  ] satisfies PrimitiveValidationCommand[];
+
+export const nextActionsForTarget = (target: string) =>
+  [
+    { command: `akan sync ${target}`, reason: "Refresh generated Akan files after source changes." },
+    { command: `akan lint ${target}`, reason: "Validate the target after generated files are refreshed." },
+  ] satisfies PrimitiveNextAction[];
+
+export const createPassedPrimitiveReport = ({
+  command,
+  changedFiles,
+  generatedFiles,
+  target,
+  nextActions,
+}: {
+  command: string;
+  changedFiles: PrimitiveChangedFile[];
+  generatedFiles?: PrimitiveGeneratedFile[];
+  target: string;
+  nextActions?: PrimitiveNextAction[];
+}) =>
+  createPrimitiveWriteReport({
+    command,
+    changedFiles,
+    generatedFiles: generatedFiles ?? [],
+    validationCommands: validationCommandsForTarget(target),
+    diagnostics: [],
+    nextActions: nextActions ?? nextActionsForTarget(target),
+  });
+
+export const scalarChangedFiles = (sys: Sys, scalarName: string, files: PrimitiveFileMap) =>
+  Object.values(files).map((file) =>
+    sourceFile(sys, `lib/__scalar/${scalarName}/${file.filename}`, "create", "Scalar source file was created."),
+  );
+
+export const titleize = (value: string) =>
+  value
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[-_]+/g, " ")
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+
+export const lowerlize = (value: string) => `${value.slice(0, 1).toLowerCase()}${value.slice(1)}`;
+
+export const normalizeFieldType = (typeName: string) => {
+  const normalizedTypes: Record<string, string> = {
+    string: "String",
+    boolean: "Boolean",
+    date: "Date",
+    int: "Int",
+    integer: "Int",
+    float: "Float",
+    double: "Float",
+    decimal: "Float",
+  };
+  return normalizedTypes[typeName.toLowerCase()] ?? typeName;
+};
+
+export const ensureBaseTypeImport = (content: string, typeName: string) => {
+  if (typeName !== "Int" && typeName !== "Float") return content;
+  if (new RegExp(`import \\{[^}]*\\b${typeName}\\b[^}]*\\} from "akanjs/base";`).test(content)) return content;
+  const baseImport = /import \{ ([^}]+) \} from "akanjs\/base";/.exec(content);
+  if (baseImport) {
+    const names = baseImport[1]
+      .split(",")
+      .map((name) => name.trim())
+      .filter(Boolean);
+    return content.replace(baseImport[0], `import { ${[...names, typeName].sort().join(", ")} } from "akanjs/base";`);
+  }
+  return `import { ${typeName} } from "akanjs/base";\n${content}`;
+};
+
+const numericDefault = (typeName: "Int" | "Float", rawDefault: string): string | null => {
+  const trimmed = rawDefault.trim();
+  if (!trimmed || !Number.isFinite(Number(trimmed))) return null;
+  if (typeName === "Int" && !/^-?\d+$/.test(trimmed)) return null;
+  return trimmed;
+};
+
+export const coerceFieldDefault = (
+  typeName: string,
+  defaultValue?: string | null,
+): { expression: string | null; diagnostic?: WorkflowDiagnostic } => {
+  if (defaultValue === undefined || defaultValue === null || defaultValue === "") return { expression: null };
+  const normalizedType = normalizeFieldType(typeName);
+  if (normalizedType === "Int" || normalizedType === "Float") {
+    const expression = numericDefault(normalizedType, defaultValue);
+    if (expression !== null) return { expression };
+    return {
+      expression: null,
+      diagnostic: {
+        severity: "error",
+        code: "primitive-default-value-invalid",
+        input: "default",
+        failureScope: "source-change",
+        message: `Default value for ${normalizedType} must be a numeric literal. Received: ${JSON.stringify(defaultValue)}.`,
+      },
+    };
+  }
+  if (normalizedType === "Boolean") {
+    const lowered = defaultValue.trim().toLowerCase();
+    if (lowered === "true" || lowered === "false") return { expression: lowered };
+    return {
+      expression: null,
+      diagnostic: {
+        severity: "error",
+        code: "primitive-default-value-invalid",
+        input: "default",
+        failureScope: "source-change",
+        message: `Default value for Boolean must be true or false. Received: ${JSON.stringify(defaultValue)}.`,
+      },
+    };
+  }
+  return { expression: JSON.stringify(defaultValue) };
+};
+
+export const fieldExpression = (typeName: string, defaultValue?: string | null) => {
+  const typeExpression = normalizeFieldType(typeName);
+  const defaultExpression = coerceFieldDefault(typeExpression, defaultValue).expression;
+  const defaultOption = defaultExpression ? `, { default: ${defaultExpression} }` : "";
+  return `field(${typeExpression}${defaultOption})`;
+};
+
+export const insertIntoObject = (content: string, className: string, line: string) => {
+  const classIndex = content.indexOf(`export class ${className} extends via`);
+  if (classIndex < 0) return null;
+  const objectEndIndex = content.indexOf("}))", classIndex);
+  if (objectEndIndex < 0) return null;
+  const prefix = content.slice(0, objectEndIndex);
+  const suffix = content.slice(objectEndIndex);
+  const insertion = prefix.endsWith("\n") ? `  ${line}\n` : `\n  ${line}\n`;
+  return `${prefix}${insertion}${suffix}`;
+};
+
+export const ensureEnumImport = (content: string) => {
+  if (content.includes("enumOf")) return content;
+  const baseImport = /import \{ ([^}]+) \} from "akanjs\/base";/.exec(content);
+  if (baseImport) {
+    const names = baseImport[1]?.split(",").map((name) => name.trim()) ?? [];
+    return content.replace(baseImport[0], `import { ${[...names, "enumOf"].sort().join(", ")} } from "akanjs/base";`);
+  }
+  return `import { enumOf } from "akanjs/base";\n${content}`;
+};
+
+export const insertEnumClass = (content: string, enumClassName: string, enumName: string, values: string[]) => {
+  if (content.includes(`export class ${enumClassName} extends enumOf`)) return content;
+  const enumClass = `export class ${enumClassName} extends enumOf("${enumName}", [\n${values
+    .map((value) => `  ${JSON.stringify(value)},`)
+    .join("\n")}\n] as const) {}\n\n`;
+  const firstClassIndex = content.indexOf("export class ");
+  if (firstClassIndex < 0) return `${content}\n${enumClass}`;
+  return `${content.slice(0, firstClassIndex)}${enumClass}${content.slice(firstClassIndex)}`;
+};
+
+export const insertDictionaryModelField = (content: string, moduleClassName: string, fieldName: string) => {
+  if (new RegExp(`\\b${fieldName}\\s*:`).test(content)) return content;
+  const label = titleize(fieldName);
+  const modelIndex = content.indexOf(`.model<${moduleClassName}>((t) => ({`);
+  if (modelIndex < 0) return null;
+  const objectEndIndex = content.indexOf("  }))", modelIndex);
+  if (objectEndIndex < 0) return null;
+  return `${content.slice(0, objectEndIndex)}    ${fieldName}: t([${JSON.stringify(label)}, ${JSON.stringify(
+    label,
+  )}]).desc([${JSON.stringify(label)}, ${JSON.stringify(label)}]),\n${content.slice(objectEndIndex)}`;
+};
+
+export const ensureConstantTypeImport = (content: string, constantPath: string, typeName: string) => {
+  if (new RegExp(`import type \\{[^}]*\\b${typeName}\\b[^}]*\\} from "${constantPath}";`).test(content)) return content;
+  const importPattern = new RegExp(`import type \\{ ([^}]+) \\} from "${constantPath}";`);
+  const existingImport = content.match(importPattern);
+  if (existingImport !== null) {
+    const names = existingImport[1]?.split(",").map((name) => name.trim()) ?? [];
+    return content.replace(
+      existingImport[0],
+      `import type { ${[...names, typeName].sort().join(", ")} } from "${constantPath}";`,
+    );
+  }
+  return `import type { ${typeName} } from "${constantPath}";\n${content}`;
+};
+
+export const insertDictionaryEnum = (content: string, enumClassName: string, enumName: string, values: string[]) => {
+  if (content.includes(`.enum<${enumClassName}>("${enumName}"`)) return content;
+  const enumBlock = `  .enum<${enumClassName}>("${enumName}", (t) => ({\n${values
+    .map((value) => `    ${value}: t([${JSON.stringify(titleize(value))}, ${JSON.stringify(titleize(value))}]),`)
+    .join("\n")}\n  }))\n`;
+  const chainEndIndex = content.lastIndexOf(";");
+  const insertBeforeIndex = [content.indexOf(".error("), content.indexOf(".translate("), chainEndIndex]
+    .filter((index) => index >= 0)
+    .sort((a, b) => a - b)[0];
+  if (insertBeforeIndex === undefined) return null;
+  return `${content.slice(0, insertBeforeIndex)}${enumBlock}${content.slice(insertBeforeIndex)}`;
+};
+
+export const parseValues = (value: string | null) =>
+  value
+    ?.split(",")
+    .map((item) => item.trim())
+    .filter(Boolean) ?? [];

package/workflow/types.ts

@@ -0,0 +1,283 @@
+import type { Sys, Workspace } from "../commandDecorators";
+
+export type WorkflowInputType = "string" | "string-list" | "surface-mode";
+export type WorkflowSurfaceMode = "infer" | "include" | "skip";
+export type WorkflowInputValue = string | string[] | WorkflowSurfaceMode;
+export type WorkflowFormat = "markdown" | "json";
+export type WorkflowPlanInputs = Record<string, string | null>;
+export type PrimitiveFormat = "markdown" | "json";
+export type UiSurface = "view" | "unit" | "template";
+export type WorkflowValidationKind = "sync" | "lint" | "typecheck" | "doctor" | "custom";
+export type WorkflowFailureScope = "workspace-config" | "environment" | "source-change" | "unknown";
+export type WorkflowValidationStatus = "passed" | "failed" | "unknown";
+export type WorkflowOverallStatus = "passed" | "failed" | "blocked-by-workspace-config" | "blocked-by-environment";
+
+export interface PrimitiveTargetInput {
+  app: string | null;
+  module: string | null;
+}
+
+export interface AddFieldInput extends PrimitiveTargetInput {
+  field: string | null;
+  type: string | null;
+  defaultValue?: string | null;
+}
+
+export interface AddEnumFieldInput extends PrimitiveTargetInput {
+  field: string | null;
+  values: string | null;
+  defaultValue?: string | null;
+}
+
+export interface WorkflowInputSpec {
+  type: WorkflowInputType;
+  required?: boolean;
+  description: string;
+  allowedValues?: readonly string[];
+}
+
+export interface WorkflowStep {
+  id: string;
+  title: string;
+  tool: string;
+  description: string;
+  when?: string;
+}
+
+export interface WorkflowPredictedChange {
+  target: string;
+  action: "inspect" | "create" | "modify" | "sync" | "validate";
+  reason: string;
+  applyScope?: "auto" | "manual-review" | "generated-sync" | "validation";
+}
+
+export interface WorkflowValidation {
+  command: string;
+  reason: string;
+  kind?: WorkflowValidationKind;
+}
+
+export interface WorkflowSpec {
+  schemaVersion: 1;
+  name: string;
+  description: string;
+  whenToUse: string;
+  inputs: Record<string, WorkflowInputSpec>;
+  optionalSurfaces?: Record<string, WorkflowSurfaceMode>;
+  steps: readonly WorkflowStep[];
+  predictedChanges: readonly WorkflowPredictedChange[];
+  validation: readonly WorkflowValidation[];
+  completionCriteria: readonly string[];
+}
+
+export interface WorkflowDiagnostic {
+  severity: "warning" | "error";
+  code: string;
+  message: string;
+  input?: string;
+  command?: string;
+  kind?: WorkflowValidationKind;
+  failureScope?: WorkflowFailureScope;
+  scope?: "baseline" | "workflow" | "unknown";
+  context?: {
+    workflow?: string;
+    planPath?: string;
+    runId?: string;
+    target?: string;
+    paths?: string[];
+  };
+}
+
+export interface WorkflowRecommendation {
+  code: string;
+  message: string;
+  kind: "auto-apply" | "validation" | "manual-action" | "import" | "placement" | "ui-component";
+  target?: string;
+  action?: string;
+  confidence?: "high" | "medium" | "low";
+}
+
+export interface WorkflowPlan {
+  schemaVersion: 1;
+  workflow: string;
+  mode: "plan";
+  inputs: Record<string, WorkflowInputValue>;
+  optionalSurfaces: Record<string, WorkflowSurfaceMode>;
+  steps: readonly WorkflowStep[];
+  predictedChanges: readonly WorkflowPredictedChange[];
+  validation: readonly WorkflowValidation[];
+  diagnostics: WorkflowDiagnostic[];
+  recommendations: WorkflowRecommendation[];
+  requiresApproval: true;
+}
+
+export interface WorkflowReport {
+  schemaVersion: 1;
+  workflow: string;
+  mode: "plan" | "dry-run" | "apply";
+  status: "passed" | "failed";
+  diagnostics: WorkflowDiagnostic[];
+  plan?: WorkflowPlan;
+}
+
+export interface WorkflowApplyCommand {
+  command: string;
+  reason: string;
+  stepId?: string;
+  kind?: WorkflowValidationKind;
+}
+
+export type WorkflowRunSource =
+  | { type: "plan"; path: string }
+  | { type: "apply-report"; path: string; runId?: string }
+  | { type: "run-report"; runId: string };
+
+export interface WorkflowValidationCommandResult {
+  command: string;
+  reason: string;
+  kind?: WorkflowValidationKind;
+  status: "passed" | "failed";
+  exitCode: number;
+  failureScope?: WorkflowFailureScope;
+  stdout?: string;
+  stderr?: string;
+}
+
+export interface WorkflowKnownBlocker {
+  code: string;
+  message: string;
+  failureScope: WorkflowFailureScope;
+  command?: string;
+  kind?: WorkflowValidationKind;
+  count: number;
+}
+
+export interface RepairAction {
+  command: string;
+  reason: string;
+  kind: "generated" | "format" | "imports" | "dictionary" | "module-shape";
+  safeToRun: boolean;
+}
+
+export interface PrimitiveChangedFile {
+  path: string;
+  action: "create" | "modify" | "remove";
+  reason: string;
+}
+
+export interface PrimitiveGeneratedFile {
+  path: string;
+  action: "sync";
+  reason: string;
+}
+
+export interface PrimitiveValidationCommand {
+  command: string;
+  reason: string;
+}
+
+export interface PrimitiveNextAction {
+  command: string;
+  reason: string;
+}
+
+export interface PrimitiveWriteReport {
+  schemaVersion: 1;
+  command: string;
+  status: "passed" | "failed";
+  changedFiles: PrimitiveChangedFile[];
+  generatedFiles: PrimitiveGeneratedFile[];
+  validationCommands: PrimitiveValidationCommand[];
+  diagnostics: WorkflowDiagnostic[];
+  nextActions: PrimitiveNextAction[];
+}
+
+export type PrimitiveFileMap = Record<string, { filename: string; content: string }>;
+
+export interface WorkflowApplyReport {
+  schemaVersion: 1;
+  runId?: string;
+  applyReportPath?: string;
+  validationTarget?: string;
+  workflow: string;
+  mode: "dry-run" | "apply";
+  status: "passed" | "failed";
+  changedFiles: PrimitiveChangedFile[];
+  generatedFiles: PrimitiveGeneratedFile[];
+  appliedCommands: WorkflowApplyCommand[];
+  recommendedValidationCommands: WorkflowApplyCommand[];
+  commands: WorkflowApplyCommand[];
+  diagnostics: WorkflowDiagnostic[];
+  recommendations: WorkflowRecommendation[];
+  nextActions: PrimitiveNextAction[];
+  plan: WorkflowPlan;
+}
+
+export interface WorkflowValidationRunReport {
+  schemaVersion: 1;
+  runId: string;
+  workflow: string;
+  mode: "validate";
+  source: WorkflowRunSource;
+  status: "passed" | "failed";
+  sourceStatus: WorkflowValidationStatus;
+  workspaceStatus: WorkflowValidationStatus;
+  overallStatus: WorkflowOverallStatus;
+  knownBlockers: WorkflowKnownBlocker[];
+  commands: WorkflowValidationCommandResult[];
+  diagnostics: WorkflowDiagnostic[];
+  baselineDiagnostics?: WorkflowDiagnostic[];
+  workflowDiagnostics?: WorkflowDiagnostic[];
+  repairActions: RepairAction[];
+  nextActions: PrimitiveNextAction[];
+  plan?: WorkflowPlan;
+}
+
+export interface RepairReport {
+  schemaVersion: 1;
+  runId?: string;
+  repairReportPath?: string;
+  command: string;
+  kind: RepairAction["kind"];
+  target: string | null;
+  status: "passed" | "failed";
+  diagnostics: WorkflowDiagnostic[];
+  repairActions: RepairAction[];
+  nextActions: PrimitiveNextAction[];
+  commands: WorkflowValidationCommandResult[];
+  generatedFiles?: PrimitiveGeneratedFile[];
+  syncedAt?: string;
+}
+
+export interface GeneratedSyncState {
+  schemaVersion: 1;
+  target: string;
+  status: "passed" | "failed";
+  syncedAt: string;
+  command: string;
+  runId?: string;
+  generatedFiles: PrimitiveGeneratedFile[];
+}
+
+export type WorkflowRunArtifact = WorkflowApplyReport | WorkflowValidationRunReport | RepairReport;
+
+export interface WorkflowStepResult {
+  changedFiles?: PrimitiveChangedFile[];
+  generatedFiles?: PrimitiveGeneratedFile[];
+  commands?: WorkflowApplyCommand[];
+  diagnostics?: WorkflowDiagnostic[];
+  recommendations?: WorkflowRecommendation[];
+  nextActions?: PrimitiveNextAction[];
+}
+
+export type WorkflowStepRunner = (step: WorkflowStep, plan: WorkflowPlan) => Promise<WorkflowStepResult | undefined>;
+export type WorkflowStepRegistry = Record<string, WorkflowStepRunner>;
+
+export interface WorkflowPrimitiveOperations {
+  workspace: Workspace;
+  createModule: (sys: Sys, module: string) => Promise<PrimitiveWriteReport>;
+  createScalar: (sys: Sys, scalar: string) => Promise<PrimitiveWriteReport>;
+  createUi: (input: PrimitiveTargetInput & { surface: UiSurface }) => Promise<PrimitiveWriteReport>;
+  addField: (input: AddFieldInput) => Promise<PrimitiveWriteReport>;
+  addEnumField: (input: AddEnumFieldInput) => Promise<PrimitiveWriteReport>;
+}

package/workflow/utils.ts

@@ -0,0 +1,23 @@
+import type { WorkflowDiagnostic, WorkflowValidationCommandResult } from "./types";
+
+export const jsonText = (value: unknown, { trailingNewline = true }: { trailingNewline?: boolean } = {}) =>
+  `${JSON.stringify(value, null, 2)}${trailingNewline ? "\n" : ""}`;
+
+export const workflowStatus = (diagnostics: readonly WorkflowDiagnostic[]) =>
+  diagnostics.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "passed";
+
+export const commandStatus = (commands: readonly WorkflowValidationCommandResult[]) =>
+  commands.some((command) => command.status === "failed") ? "failed" : "passed";
+
+export const uniqueBy = <T>(values: readonly T[], key: (value: T) => string) => {
+  const seen = new Set<string>();
+  return values.filter((value) => {
+    const itemKey = key(value);
+    if (seen.has(itemKey)) return false;
+    seen.add(itemKey);
+    return true;
+  });
+};
+
+export const compactDiagnostics = (diagnostics: Array<WorkflowDiagnostic | false | null | undefined>) =>
+  diagnostics.filter((diagnostic): diagnostic is WorkflowDiagnostic => !!diagnostic);