@zucker-framework/cli 1.0.0 → 1.0.2

package/dist/tooling.mjs

@@ -0,0 +1,516 @@
+import {
+  __name
+} from "./chunk-O6YSETKJ.mjs";
+
+// src/tooling/module-wiring.ts
+import { readdirSync, readFileSync, statSync } from "fs";
+import { relative, resolve } from "path";
+import ts from "typescript";
+var LIFECYCLE_INTERFACES = /* @__PURE__ */ new Set([
+  "BeforeApplicationShutdown",
+  "OnApplicationBootstrap",
+  "OnApplicationShutdown",
+  "OnModuleDestroy",
+  "OnModuleInit"
+]);
+var LIFECYCLE_METHODS = /* @__PURE__ */ new Set([
+  "beforeApplicationShutdown",
+  "onApplicationBootstrap",
+  "onApplicationShutdown",
+  "onModuleDestroy",
+  "onModuleInit"
+]);
+function listTypeScriptFiles(directory) {
+  const files = [];
+  for (const entry of readdirSync(directory, {
+    withFileTypes: true
+  })) {
+    const path = resolve(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listTypeScriptFiles(path));
+    } else if (entry.isFile() && entry.name.endsWith(".ts") && !entry.name.endsWith(".spec.ts") && !entry.name.endsWith(".test.ts")) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+__name(listTypeScriptFiles, "listTypeScriptFiles");
+function getImportAliases(sourceFile) {
+  const aliases = /* @__PURE__ */ new Map();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const element of bindings.elements) {
+      aliases.set(element.name.text, element.propertyName?.text ?? element.name.text);
+    }
+  }
+  return aliases;
+}
+__name(getImportAliases, "getImportAliases");
+function getScheduleModuleImports(sourceFile) {
+  const cron = /* @__PURE__ */ new Set();
+  const modules = /* @__PURE__ */ new Set();
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== "@nestjs/schedule") {
+      continue;
+    }
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings) continue;
+    if (ts.isNamespaceImport(bindings)) {
+      namespaces.add(bindings.name.text);
+      continue;
+    }
+    for (const element of bindings.elements) {
+      const importedName = element.propertyName?.text ?? element.name.text;
+      if (importedName === "ScheduleModule") {
+        modules.add(element.name.text);
+      } else if (importedName === "Cron") {
+        cron.add(element.name.text);
+      }
+    }
+  }
+  return {
+    cron,
+    modules,
+    namespaces
+  };
+}
+__name(getScheduleModuleImports, "getScheduleModuleImports");
+function isImportedScheduleModule(expression, imports) {
+  if (ts.isIdentifier(expression)) {
+    return imports.modules.has(expression.text);
+  }
+  return ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.expression) && imports.namespaces.has(expression.expression.text) && expression.name.text === "ScheduleModule";
+}
+__name(isImportedScheduleModule, "isImportedScheduleModule");
+function isImportedCron(expression, imports) {
+  if (ts.isIdentifier(expression)) {
+    return imports.cron.has(expression.text);
+  }
+  return ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.expression) && imports.namespaces.has(expression.expression.text) && expression.name.text === "Cron";
+}
+__name(isImportedCron, "isImportedCron");
+function waitsForCompletion(call) {
+  const options = call.arguments[1];
+  if (!options || !ts.isObjectLiteralExpression(options)) return false;
+  const property = findProperty(options, "waitForCompletion");
+  return property?.initializer.kind === ts.SyntaxKind.TrueKeyword;
+}
+__name(waitsForCompletion, "waitsForCompletion");
+function enclosingClassName(node) {
+  let current = node.parent;
+  while (current) {
+    if (ts.isClassDeclaration(current)) return current.name?.text;
+    current = current.parent;
+  }
+  return void 0;
+}
+__name(enclosingClassName, "enclosingClassName");
+function getCronClassNames(sourceFile, scheduleImports) {
+  const names = [];
+  const visit = /* @__PURE__ */ __name((node) => {
+    if (ts.isCallExpression(node) && ts.isDecorator(node.parent) && isImportedCron(node.expression, scheduleImports)) {
+      const className = enclosingClassName(node);
+      if (className) names.push(className);
+    }
+    ts.forEachChild(node, visit);
+  }, "visit");
+  visit(sourceFile);
+  return names;
+}
+__name(getCronClassNames, "getCronClassNames");
+function expressionName(expression, aliases) {
+  if (!expression) return void 0;
+  if (ts.isIdentifier(expression)) {
+    return aliases.get(expression.text) ?? expression.text;
+  }
+  if (ts.isParenthesizedExpression(expression)) {
+    return expressionName(expression.expression, aliases);
+  }
+  if (ts.isAsExpression(expression) || ts.isTypeAssertionExpression(expression)) {
+    return expressionName(expression.expression, aliases);
+  }
+  return void 0;
+}
+__name(expressionName, "expressionName");
+function propertyName(property) {
+  const name = property.name;
+  if (!name) return void 0;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+  return void 0;
+}
+__name(propertyName, "propertyName");
+function findProperty(object, name) {
+  return object.properties.find((property) => ts.isPropertyAssignment(property) && propertyName(property) === name);
+}
+__name(findProperty, "findProperty");
+function getModuleMetadata(sourceFile, aliases) {
+  const metadata = [];
+  const visit = /* @__PURE__ */ __name((node) => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && expressionName(node.expression, aliases) === "Module" && node.arguments.length === 1 && ts.isObjectLiteralExpression(node.arguments[0])) {
+      metadata.push(node.arguments[0]);
+    }
+    ts.forEachChild(node, visit);
+  }, "visit");
+  visit(sourceFile);
+  return metadata;
+}
+__name(getModuleMetadata, "getModuleMetadata");
+function getProviders(metadata) {
+  const providers = findProperty(metadata, "providers");
+  if (!providers || !ts.isArrayLiteralExpression(providers.initializer)) return [];
+  return providers.initializer.elements.filter((element) => !ts.isSpreadElement(element));
+}
+__name(getProviders, "getProviders");
+function getImplementedLifecycleNames(sourceFile, aliases) {
+  const names = [];
+  const visit = /* @__PURE__ */ __name((node) => {
+    if (ts.isClassDeclaration(node) && node.name) {
+      const implementsLifecycle = (node.heritageClauses ?? []).some((clause) => clause.token === ts.SyntaxKind.ImplementsKeyword && clause.types.some((type) => {
+        const localName = type.expression.getText(sourceFile).split(".").at(-1);
+        const name = localName ? aliases.get(localName) ?? localName : void 0;
+        return name && LIFECYCLE_INTERFACES.has(name);
+      }));
+      const declaresLifecycleHook = node.members.some((member) => {
+        const name = propertyName(member);
+        return name ? LIFECYCLE_METHODS.has(name) : false;
+      });
+      if (implementsLifecycle || declaresLifecycleHook) names.push(node.name.text);
+    }
+    ts.forEachChild(node, visit);
+  }, "visit");
+  visit(sourceFile);
+  return names;
+}
+__name(getImplementedLifecycleNames, "getImplementedLifecycleNames");
+function factoryReturnsInjectedInstance(factory, injectedParameterNames) {
+  const returnsInjected = /* @__PURE__ */ __name((expression) => {
+    if (ts.isIdentifier(expression)) {
+      return injectedParameterNames.has(expression.text);
+    }
+    if (ts.isParenthesizedExpression(expression)) {
+      return returnsInjected(expression.expression);
+    }
+    if (ts.isAsExpression(expression) || ts.isTypeAssertionExpression(expression)) {
+      return returnsInjected(expression.expression);
+    }
+    if (ts.isConditionalExpression(expression)) {
+      return returnsInjected(expression.whenTrue) || returnsInjected(expression.whenFalse);
+    }
+    return false;
+  }, "returnsInjected");
+  if (!ts.isArrowFunction(factory) && !ts.isFunctionExpression(factory)) {
+    return false;
+  }
+  if (!ts.isBlock(factory.body)) return returnsInjected(factory.body);
+  let unsafe = false;
+  const visit = /* @__PURE__ */ __name((node) => {
+    if (ts.isReturnStatement(node) && node.expression) {
+      unsafe ||= returnsInjected(node.expression);
+    }
+    ts.forEachChild(node, visit);
+  }, "visit");
+  visit(factory.body);
+  return unsafe;
+}
+__name(factoryReturnsInjectedInstance, "factoryReturnsInjectedInstance");
+function location(sourceRoot, file, node, sourceFile) {
+  const start = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return `${relative(sourceRoot, file)}:${start.line + 1}`;
+}
+__name(location, "location");
+function finding(code, message, at) {
+  return {
+    code,
+    message,
+    location: at
+  };
+}
+__name(finding, "finding");
+function auditModuleWiring({ sourceRoot, schedulerRoot, globalGuards, infrastructureProviders = {} }) {
+  const expectedGlobalGuards = /* @__PURE__ */ new Set([
+    ...(globalGuards?.classes ?? []).map((name) => `useClass:${name}`),
+    ...(globalGuards?.factories ?? []).map((name) => `useFactory:${name}`)
+  ]);
+  if (!statSync(sourceRoot).isDirectory()) {
+    throw new Error(`Module source root is not a directory: ${sourceRoot}`);
+  }
+  const files = listTypeScriptFiles(sourceRoot);
+  const parsed = files.map((file) => {
+    const source = readFileSync(file, "utf8");
+    const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    return {
+      aliases: getImportAliases(sourceFile),
+      file,
+      scheduleImports: getScheduleModuleImports(sourceFile),
+      sourceFile
+    };
+  });
+  const lifecycleClasses = new Set(parsed.flatMap(({ aliases, sourceFile }) => getImplementedLifecycleNames(sourceFile, aliases)));
+  const cronClasses = new Set(parsed.flatMap(({ scheduleImports, sourceFile }) => getCronClassNames(sourceFile, scheduleImports)));
+  const findings = [];
+  const schedules = [];
+  const cronJobs = [];
+  const guards = [];
+  const coreProviders = Object.fromEntries(Object.keys(infrastructureProviders).map((name) => [
+    name,
+    []
+  ]));
+  const lifecycleProviders = /* @__PURE__ */ new Map();
+  const cronProviders = /* @__PURE__ */ new Map();
+  for (const { aliases, file, scheduleImports, sourceFile } of parsed) {
+    const relativeFile = relative(sourceRoot, file);
+    const visitSchedule = /* @__PURE__ */ __name((node) => {
+      if (ts.isCallExpression(node) && ts.isDecorator(node.parent) && isImportedCron(node.expression, scheduleImports)) {
+        const at = location(sourceRoot, file, node, sourceFile);
+        cronJobs.push(at);
+        if (!waitsForCompletion(node)) {
+          findings.push(finding("cron-overlap-guard", "@Cron jobs must set waitForCompletion: true to prevent overlapping runs in one process", at));
+        }
+      }
+      if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "forRoot" && isImportedScheduleModule(node.expression.expression, scheduleImports)) {
+        schedules.push(location(sourceRoot, file, node, sourceFile));
+      }
+      ts.forEachChild(node, visitSchedule);
+    }, "visitSchedule");
+    visitSchedule(sourceFile);
+    for (const metadata of getModuleMetadata(sourceFile, aliases)) {
+      for (const provider of getProviders(metadata)) {
+        const directName = expressionName(provider, aliases);
+        if (directName && Object.hasOwn(coreProviders, directName)) {
+          coreProviders[directName].push(location(sourceRoot, file, provider, sourceFile));
+        }
+        if (directName && lifecycleClasses.has(directName)) {
+          const locations = lifecycleProviders.get(directName) ?? [];
+          locations.push(location(sourceRoot, file, provider, sourceFile));
+          lifecycleProviders.set(directName, locations);
+        }
+        if (directName && cronClasses.has(directName)) {
+          const locations = cronProviders.get(directName) ?? [];
+          locations.push(location(sourceRoot, file, provider, sourceFile));
+          cronProviders.set(directName, locations);
+        }
+        if (!ts.isObjectLiteralExpression(provider)) continue;
+        const provide = findProperty(provider, "provide");
+        const useClass = findProperty(provider, "useClass");
+        const factory = findProperty(provider, "useFactory");
+        const useClassName = useClass ? expressionName(useClass.initializer, aliases) : void 0;
+        if (useClassName && Object.hasOwn(coreProviders, useClassName)) {
+          coreProviders[useClassName].push(location(sourceRoot, file, provider, sourceFile));
+        }
+        if (useClassName && lifecycleClasses.has(useClassName)) {
+          const locations = lifecycleProviders.get(useClassName) ?? [];
+          locations.push(location(sourceRoot, file, provider, sourceFile));
+          lifecycleProviders.set(useClassName, locations);
+        }
+        if (useClassName && cronClasses.has(useClassName)) {
+          const locations = cronProviders.get(useClassName) ?? [];
+          locations.push(location(sourceRoot, file, provider, sourceFile));
+          cronProviders.set(useClassName, locations);
+        }
+        if (provide && expressionName(provide.initializer, aliases) === "APP_GUARD") {
+          const factoryName = factory ? expressionName(factory.initializer, aliases) : void 0;
+          guards.push({
+            identity: useClassName && !factory ? `useClass:${useClassName}` : factoryName && !useClass ? `useFactory:${factoryName}` : void 0,
+            location: location(sourceRoot, file, provider, sourceFile),
+            relativeFile
+          });
+        }
+        const useExisting = findProperty(provider, "useExisting");
+        const existingName = useExisting ? expressionName(useExisting.initializer, aliases) : void 0;
+        if (existingName && lifecycleClasses.has(existingName)) {
+          findings.push(finding("lifecycle-provider-alias", `${existingName} implements a Nest lifecycle hook and must not be exposed through useExisting`, location(sourceRoot, file, provider, sourceFile)));
+        }
+        const inject = findProperty(provider, "inject");
+        if (!factory || !inject || !ts.isArrayLiteralExpression(inject.initializer) || !ts.isArrowFunction(factory.initializer) && !ts.isFunctionExpression(factory.initializer)) {
+          continue;
+        }
+        const factoryFunction = factory.initializer;
+        const injectedParameterNames = /* @__PURE__ */ new Set();
+        inject.initializer.elements.forEach((element, index) => {
+          const injectedName = expressionName(element, aliases);
+          const parameter = factoryFunction.parameters[index];
+          if (injectedName && lifecycleClasses.has(injectedName) && parameter && ts.isIdentifier(parameter.name)) {
+            injectedParameterNames.add(parameter.name.text);
+          }
+        });
+        if (injectedParameterNames.size > 0 && factoryReturnsInjectedInstance(factory.initializer, injectedParameterNames)) {
+          findings.push(finding("lifecycle-provider-factory-alias", "factory returns an injected lifecycle provider directly; Nest can invoke its hooks through both provider wrappers", location(sourceRoot, file, provider, sourceFile)));
+        }
+      }
+    }
+  }
+  if (schedulerRoot && (schedules.length !== 1 || !schedules[0]?.startsWith(`${schedulerRoot}:`))) {
+    findings.push(finding("schedule-root-count", `ScheduleModule.forRoot() must appear exactly once in ${schedulerRoot}; found ${schedules.length}`, schedules.join(", ") || "not found"));
+  }
+  for (const [provider, expectedFile] of Object.entries(infrastructureProviders)) {
+    const locations = coreProviders[provider];
+    if (locations.length !== 1 || !locations[0].startsWith(`${expectedFile}:`)) {
+      findings.push(finding("infrastructure-provider-owner", `${provider} must be provided exactly once by ${expectedFile}; found ${locations.length}`, locations.join(", ") || "not found"));
+    }
+  }
+  const guardNames = guards.map(({ identity }) => identity).filter((name) => Boolean(name));
+  const duplicateGuards = guardNames.filter((name, index) => guardNames.indexOf(name) !== index);
+  const actualGuardSet = new Set(guardNames);
+  if (globalGuards && (guards.some(({ relativeFile }) => relativeFile !== globalGuards.owner) || guards.some(({ identity }) => !identity) || duplicateGuards.length > 0 || actualGuardSet.size !== expectedGlobalGuards.size || [
+    ...expectedGlobalGuards
+  ].some((name) => !actualGuardSet.has(name)))) {
+    findings.push(finding("global-guard-composition", `APP_GUARD must be registered once per expected guard in ${globalGuards.owner}; found ${guardNames.join(", ") || "none"}`, guards.map(({ location: at }) => at).join(", ") || "not found"));
+  }
+  for (const [className, locations] of lifecycleProviders) {
+    if (locations.length > 1) {
+      findings.push(finding("duplicate-lifecycle-provider", `${className} is provided by multiple modules and would have multiple lifecycle owners`, locations.join(", ")));
+    }
+  }
+  for (const className of cronClasses) {
+    const locations = cronProviders.get(className) ?? [];
+    if (locations.length !== 1) {
+      findings.push(finding("cron-provider-owner", `${className} contains @Cron jobs and must be provided exactly once; found ${locations.length}`, locations.join(", ") || "not found"));
+    }
+  }
+  return {
+    ok: findings.length === 0,
+    findings,
+    stats: {
+      files: files.length,
+      cronJobs: cronJobs.length,
+      cronProviders: cronProviders.size,
+      globalGuards: guards.length,
+      lifecycleClasses: lifecycleClasses.size,
+      scheduleRoots: schedules.length
+    }
+  };
+}
+__name(auditModuleWiring, "auditModuleWiring");
+
+// src/tooling/transaction-boundaries.ts
+import { readdirSync as readdirSync2, readFileSync as readFileSync2 } from "fs";
+import { join } from "path";
+import ts2 from "typescript";
+function findTransactionBoundaryViolations(source, fileName, policy) {
+  const sourceFile = ts2.createSourceFile(fileName, source, ts2.ScriptTarget.Latest, true);
+  const violations = [];
+  const addViolation = /* @__PURE__ */ __name((node, message) => {
+    violations.push({
+      file: fileName,
+      line: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1,
+      message
+    });
+  }, "addViolation");
+  const inspectTransaction = /* @__PURE__ */ __name((callback) => {
+    const transactionClient = callback.parameters[0]?.name.getText(sourceFile);
+    if (!transactionClient) return;
+    const inspectBody = /* @__PURE__ */ __name((node) => {
+      if (ts2.isCallExpression(node)) {
+        const callee = node.expression.getText(sourceFile);
+        if (policy.rootClientNames.some((name) => callee.startsWith(`${name}.`) && transactionClient !== name)) {
+          addViolation(node, "interactive transaction uses the root Prisma client");
+        }
+        if (callee === "Promise.all" || callee === "Promise.allSettled") {
+          addViolation(node, "interactive transaction runs parallel work");
+        }
+        if (policy.externalCallPattern.test(callee)) {
+          addViolation(node, `interactive transaction performs external work via ${callee}`);
+        }
+        if (policy.transactionClientRequiredPattern.test(callee) && !node.arguments.some((argument) => argument.getText(sourceFile) === transactionClient)) {
+          addViolation(node, `service call ${callee} does not receive the transaction client`);
+        }
+      }
+      ts2.forEachChild(node, inspectBody);
+    }, "inspectBody");
+    inspectBody(callback.body);
+  }, "inspectTransaction");
+  const visit = /* @__PURE__ */ __name((node) => {
+    if (ts2.isCallExpression(node) && node.expression.getText(sourceFile).endsWith(".$transaction")) {
+      const callback = node.arguments[0];
+      if (callback && (ts2.isArrowFunction(callback) || ts2.isFunctionExpression(callback))) inspectTransaction(callback);
+    }
+    ts2.forEachChild(node, visit);
+  }, "visit");
+  visit(sourceFile);
+  return violations;
+}
+__name(findTransactionBoundaryViolations, "findTransactionBoundaryViolations");
+function checkTransactionBoundaries(rootDirectory, policy) {
+  const scan = /* @__PURE__ */ __name((directory) => readdirSync2(directory, {
+    withFileTypes: true
+  }).flatMap((entry) => {
+    const entryPath = join(directory, entry.name);
+    if (entry.isDirectory()) return scan(entryPath);
+    if (!entry.name.endsWith(".ts") || entry.name.endsWith(".spec.ts")) return [];
+    return findTransactionBoundaryViolations(readFileSync2(entryPath, "utf8"), entryPath, policy);
+  }), "scan");
+  return scan(rootDirectory);
+}
+__name(checkTransactionBoundaries, "checkTransactionBoundaries");
+
+// src/tooling/framework-boundaries.ts
+var PUBLIC_FRAMEWORK_SUBPATHS = /* @__PURE__ */ new Set([
+  "@zucker-framework/cli/agent-instructions",
+  "@zucker-framework/ai/langchain",
+  "@zucker-framework/core/privacy",
+  "@zucker-framework/core/user-agent"
+]);
+function auditFrameworkSourceText(file, source, rules = []) {
+  const violations = [];
+  const normalizedFile = file.replaceAll("\\", "/");
+  for (const specifier of importedSpecifiers(source)) {
+    if (specifier.startsWith("@zucker/")) {
+      violations.push(`${file}: replace retired @zucker/ imports with @zucker-framework/`);
+    }
+    if (specifier.startsWith("@zucker-framework/")) {
+      const segments = specifier.split("/");
+      if (segments.length !== 2 && !PUBLIC_FRAMEWORK_SUBPATHS.has(specifier)) {
+        violations.push(`${file}: import ${specifier} through a documented package public API`);
+      }
+    }
+    if (specifier.includes("zucker-framework/packages/") || specifier.includes("zucker-framework/src/")) {
+      violations.push(`${file}: do not import Zucker Framework source directly`);
+    }
+    for (const rule of rules) {
+      if (specifier === rule.specifier && rule.matchesFile(normalizedFile)) {
+        violations.push(`${file}: ${rule.message}`);
+      }
+    }
+  }
+  return violations;
+}
+__name(auditFrameworkSourceText, "auditFrameworkSourceText");
+function auditPnpmWorkflowVersions(packageManager, workflowSources) {
+  const violations = [];
+  if (!/^pnpm@\d+\.\d+\.\d+$/.test(packageManager ?? "")) {
+    violations.push("package.json: packageManager must pin an exact pnpm version");
+    return violations;
+  }
+  const expectedPnpm = packageManager.slice("pnpm@".length);
+  for (const [file, source] of workflowSources) {
+    const setupPattern = /uses:\s*pnpm\/action-setup@[^\n]+/g;
+    let match;
+    while (match = setupPattern.exec(source)) {
+      const setupBlock = source.slice(match.index, match.index + 260);
+      const configuredPnpm = setupBlock.match(/\n\s*version:\s*([^\s#]+)/)?.[1];
+      if (configuredPnpm !== expectedPnpm) {
+        violations.push(`${file}: pnpm ${configuredPnpm ?? "missing"} does not match packageManager ${expectedPnpm}`);
+      }
+    }
+  }
+  return violations;
+}
+__name(auditPnpmWorkflowVersions, "auditPnpmWorkflowVersions");
+function importedSpecifiers(source) {
+  const specifiers = [];
+  const importPattern = /(?:\bfrom\s*|\bimport\s*(?:\(\s*)?|\brequire\s*\(\s*)["']([^"']+)["']/g;
+  let match;
+  while (match = importPattern.exec(source)) specifiers.push(match[1]);
+  return specifiers;
+}
+__name(importedSpecifiers, "importedSpecifiers");
+export {
+  auditFrameworkSourceText,
+  auditModuleWiring,
+  auditPnpmWorkflowVersions,
+  checkTransactionBoundaries,
+  findTransactionBoundaryViolations
+};

package/package.json

@@ -1,25 +1,28 @@
 {
   "name": "@zucker-framework/cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CLI tool for Zucker Framework — scaffolding, diagnostics, and module management",
   "bin": {
     "zucker": "./dist/index.js"
   },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/tooling.js",
+  "types": "dist/tooling.d.ts",
   "files": [
     "dist",
     "LICENSE",
     "NOTICE",
-    "THIRD_PARTY_NOTICES"
+    "THIRD_PARTY_NOTICES",
+    "tooling/agent-instructions.mjs",
+    "tooling/agent-instructions.d.mts"
   ],
   "dependencies": {
-    "@zucker-framework/ai-access": "1.0.0",
+    "@zucker-framework/ai-access": "1.0.2",
     "chalk": "^6.0.0",
     "commander": "^15.0.0",
     "dotenv": "^17.4.2",
     "openai": "7.8.0",
-    "pg": "8.23.0"
+    "pg": "8.23.0",
+    "typescript": "^6.0.3"
   },
   "devDependencies": {
     "@types/node": "^20.19.43",
@@ -39,8 +42,26 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "module": "dist/tooling.mjs",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/tooling.d.mts",
+        "default": "./dist/tooling.mjs"
+      },
+      "require": {
+        "types": "./dist/tooling.d.ts",
+        "default": "./dist/tooling.js"
+      }
+    },
+    "./agent-instructions": {
+      "types": "./tooling/agent-instructions.d.mts",
+      "import": "./tooling/agent-instructions.mjs",
+      "default": "./tooling/agent-instructions.mjs"
+    }
+  },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs --dts && node ../../scripts/prepare-cli-catalog.mjs",
+    "build": "tsup --config tsup.config.ts && node ../../scripts/prepare-cli-catalog.mjs",
     "clean": "rm -rf dist",
     "lint": "eslint src/"
   }

package/tooling/agent-instructions.d.mts

@@ -0,0 +1,25 @@
+export interface AgentInstructionPolicy {
+  skillsDirectory: string;
+  documents: readonly string[];
+  rootDocument: string;
+  compatibilityLinks: readonly {
+    path: string;
+    target?: string;
+    optional?: boolean;
+  }[];
+  skillAliasDirectories: readonly string[];
+  allowSkillReferenceAliases?: boolean;
+  checkGit?: boolean;
+}
+
+export interface AgentInstructionAudit {
+  errors: string[];
+  skills: number;
+  aliases: number;
+}
+
+/** Read the selected local instruction documents and optionally inspect Git ignore visibility. */
+export declare function auditAgentInstructions(
+  repository: string,
+  policy: AgentInstructionPolicy,
+): AgentInstructionAudit;