@kb-labs/devlink-contracts 1.5.0

package/LICENSE

@@ -0,0 +1,4 @@
+This project is licensed under the same terms as the KB Labs Plugin Template root project.
+
+See the root LICENSE file at the repository root for full details.
+

package/README.md

@@ -0,0 +1,90 @@
+# @kb-labs/plugin-template-contracts
+
+Lightweight public contracts package for the plugin: it describes guaranteed artifacts, commands, workflows, API payloads, and the version of these promises.
+
+## Why this package exists
+
+Every KB Labs plugin is expected to publish a clear, lightweight “promise” to the rest of the ecosystem. This package is that promise: it contains only types, manifests, and validation helpers, so other teams (CLI, Workflow Engine, Studio, REST, marketplace tooling) can rely on a single source of truth without dragging in plugin runtime code.
+
+## Quick start checklist
+
+1. Clone this package as part of your plugin workspace (`packages/contracts`).
+2. Update `pluginContractsManifest` with your plugin ID and initial artifacts/commands.
+3. Adjust Zod schemas in `src/schema.ts` (or add new ones) to match your payloads.
+4. Bump `contractsVersion` whenever the public promise changes (SemVer rules below).
+5. Run `pnpm test` and `pnpm type-check` to ensure the manifest validates.
+6. Import the manifest in your CLI/REST/workflow code to avoid hard-coded IDs.
+
+### Renaming this package
+
+When you turn the template into your own plugin:
+- Change the npm name in `package.json` (e.g. `@kb-labs/my-plugin-contracts`).
+- Update `pluginContractsManifest.pluginId` in `src/contract.ts`.
+- Adjust aliases in `tsconfig.paths.json` and imports across the workspace (`@kb-labs/plugin-template-contracts` → your new name).
+- Replace sample artifact IDs (`template.hello.*`) with your own naming scheme.
+
+## What's inside
+
+- `pluginContractsManifest` — the single source of truth for the plugin's public capabilities
+- TypeScript types (`src/types`) and Zod schemas (`src/schema`) for artifacts, commands, workflows, and API payloads
+- `parsePluginContracts` utility for runtime validation of the manifest and third-party contracts
+
+## Versioning rules
+
+- `contractsVersion` follows SemVer and is **independent** from the plugin's npm version.
+- **MAJOR** — breaking changes (removing/renaming artifacts, changing payload formats).
+- **MINOR** — backwards-compatible extensions (new artifacts, commands, fields).
+- **PATCH** — documentation/metadata updates without altering payload formats.
+
+## Minimal manifest example
+
+```ts
+import type { PluginContracts } from '@kb-labs/plugin-template-contracts';
+
+export const pluginContractsManifest: PluginContracts = {
+  schema: 'kb.plugin.contracts/1',
+  pluginId: '@kb-labs/my-plugin',
+  contractsVersion: '1.0.0',
+  artifacts: {
+    'my-plugin.result': {
+      id: 'my-plugin.result',
+      kind: 'json',
+      description: 'Primary output of the CLI command.'
+    }
+  }
+  // commands/workflows/api can be added later when needed
+};
+```
+
+## Optional sections
+
+All additional sections are **optional** — include only what your plugin actually supports:
+
+- `commands` — define CLI or workflow commands that produce/consume artifacts.
+- `workflows` — describe composed workflows and their steps.
+- `api` — document REST (or future surfaces) when the plugin exposes them.
+
+If your plugin only ships a CLI command, keep `commands` + `artifacts` and omit `workflows`/`api`. The Zod schema accepts missing sections.
+
+## Usage in plugin code
+
+```ts
+import { pluginContractsManifest } from '@kb-labs/plugin-template-contracts';
+
+const helloArtifactId = pluginContractsManifest.artifacts['template.hello.greeting'].id;
+```
+
+Use the manifest to avoid magic strings, assert that required artifacts exist, or log which promises were fulfilled.
+
+## Who relies on the contract
+
+- **Workflow Engine** — verifies allowed steps, required artifacts, and matches produced results with the contract.
+- **Studio** — builds UI and hints based on declared artifacts and commands.
+- **CLI / REST / other plugins** — reuse types and schemas as the source of truth, validate inputs/outputs.
+- **Marketplace & QA tooling** — checks plugin compatibility and correctness before publishing.
+
+## Looking ahead
+
+- Generate JSON Schema / OpenAPI from the `api` contract surface.
+- Add automatic inspectors in Studio and validators for the marketplace.
+

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+export { DependencyMode, DependencyModeSchema, DevlinkBackup, DevlinkBackupSchema, DevlinkMode, DevlinkModeSchema, DevlinkPlan, DevlinkPlanItem, DevlinkPlanItemSchema, DevlinkPlanSchema, DevlinkState, DevlinkStateSchema, DevlinkStatus, DevlinkStatusSchema, DiagnosticIssue, DiagnosticIssueSchema, PackageEntry, PackageEntrySchema, PackageMap, PackageMapSchema } from './schema.js';
+import 'zod';
+
+/**
+ * Flag definitions for DevLink CLI commands.
+ * Defined once here, reused in both manifest.ts and command handlers.
+ */
+declare const switchFlags: {
+    mode: {
+        type: "string";
+        description: string;
+        choices: string[];
+        alias: string;
+        demandOption: boolean;
+    };
+    'dry-run': {
+        type: "boolean";
+        description: string;
+        default: boolean;
+        alias: string;
+    };
+    repos: {
+        type: "string";
+        description: string;
+        alias: string;
+    };
+    yes: {
+        type: "boolean";
+        description: string;
+        default: boolean;
+        alias: string;
+    };
+    json: {
+        type: "boolean";
+        description: string;
+        default: boolean;
+    };
+    ttl: {
+        type: "number";
+        description: string;
+        default: number;
+    };
+};
+declare const statusFlags: {
+    json: {
+        type: "boolean";
+        description: string;
+        default: boolean;
+    };
+    verbose: {
+        type: "boolean";
+        description: string;
+        default: boolean;
+        alias: string;
+    };
+};
+declare const planFlags: {
+    mode: {
+        type: "string";
+        description: string;
+        choices: string[];
+        alias: string;
+    };
+    repos: {
+        type: "string";
+        description: string;
+        alias: string;
+    };
+    json: {
+        type: "boolean";
+        description: string;
+        default: boolean;
+    };
+    ttl: {
+        type: "number";
+        description: string;
+        default: number;
+    };
+};
+declare const freezeFlags: {
+    json: {
+        type: "boolean";
+        description: string;
+        default: boolean;
+    };
+};
+declare const undoFlags: {
+    json: {
+        type: "boolean";
+        description: string;
+        default: boolean;
+    };
+};
+declare const backupsFlags: {
+    restore: {
+        type: "string";
+        description: string;
+        alias: string;
+    };
+    json: {
+        type: "boolean";
+        description: string;
+        default: boolean;
+    };
+};
+type SwitchFlags = typeof switchFlags;
+type StatusFlags = typeof statusFlags;
+type PlanFlags = typeof planFlags;
+type FreezeFlags = typeof freezeFlags;
+type UndoFlags = typeof undoFlags;
+type BackupsFlags = typeof backupsFlags;
+
+/** Cache namespace prefix for devlink — used in manifest and npm checker */
+declare const DEVLINK_CACHE_PREFIX: "devlink:";
+
+export { type BackupsFlags, DEVLINK_CACHE_PREFIX, type FreezeFlags, type PlanFlags, type StatusFlags, type SwitchFlags, type UndoFlags, backupsFlags, freezeFlags, planFlags, statusFlags, switchFlags, undoFlags };

package/dist/index.js

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+
+// src/schema.ts
+var DevlinkModeSchema = z.enum(["local", "npm", "auto"]);
+var PackageEntrySchema = z.object({
+  /** npm package name e.g. @kb-labs/core-platform */
+  name: z.string(),
+  /** Relative path for link: resolution e.g. ../kb-labs-core/packages/core-platform */
+  linkPath: z.string(),
+  /** npm version e.g. ^1.0.0 */
+  npmVersion: z.string(),
+  /** Source monorepo dir name e.g. kb-labs-core */
+  monorepo: z.string(),
+  /** Whether package.json has "private": true (stays as link: in npm mode) */
+  private: z.boolean().optional()
+});
+var PackageMapSchema = z.record(z.string(), PackageEntrySchema);
+var DevlinkPlanItemSchema = z.object({
+  /** Absolute path to the package.json file to modify */
+  packageJsonPath: z.string(),
+  /** Relative path to packageJsonPath from repo root (for display) */
+  packageJsonRel: z.string(),
+  /** Owner monorepo e.g. kb-labs-cli */
+  monorepo: z.string(),
+  /** The dependency package being changed e.g. @kb-labs/core-platform */
+  depName: z.string(),
+  /** Current value in package.json */
+  from: z.string(),
+  /** New value to write */
+  to: z.string(),
+  /** Section: dependencies | devDependencies | peerDependencies */
+  section: z.enum(["dependencies", "devDependencies", "peerDependencies"])
+});
+var DevlinkPlanSchema = z.object({
+  mode: DevlinkModeSchema,
+  items: z.array(DevlinkPlanItemSchema),
+  timestamp: z.string(),
+  /** Filtered to specific repos if --repos flag was used */
+  scopedRepos: z.array(z.string()).optional()
+});
+var DevlinkStateSchema = z.object({
+  currentMode: DevlinkModeSchema.nullable(),
+  lastApplied: z.string().nullable(),
+  frozenAt: z.string().nullable()
+});
+var DevlinkBackupSchema = z.object({
+  id: z.string(),
+  timestamp: z.string(),
+  description: z.string(),
+  /** List of package.json paths that were backed up */
+  files: z.array(z.string()),
+  /** Mode that was active before backup was created */
+  modeAtBackup: DevlinkModeSchema.nullable()
+});
+var DiagnosticIssueSchema = z.object({
+  type: z.enum(["broken-link", "cross-repo-workspace", "stale-lockfile", "stale-workspace-yaml"]),
+  severity: z.enum(["error", "warning"]),
+  file: z.string(),
+  dep: z.string().optional(),
+  message: z.string(),
+  fix: z.string()
+});
+var DependencyModeSchema = z.enum(["local", "npm", "workspace", "mixed", "unknown"]);
+var DevlinkStatusSchema = z.object({
+  currentMode: DevlinkModeSchema.nullable(),
+  lastApplied: z.string().nullable(),
+  linkCount: z.number(),
+  npmCount: z.number(),
+  workspaceCount: z.number(),
+  discrepancies: z.array(z.object({
+    packageJsonPath: z.string(),
+    depName: z.string(),
+    value: z.string(),
+    expected: z.string()
+  }))
+});
+
+// src/flags.ts
+var switchFlags = {
+  mode: {
+    type: "string",
+    description: "Linking mode: local (link:), npm (^version), auto",
+    choices: ["local", "npm", "auto"],
+    alias: "m",
+    demandOption: true
+  },
+  "dry-run": {
+    type: "boolean",
+    description: "Preview changes without applying them",
+    default: false,
+    alias: "d"
+  },
+  repos: {
+    type: "string",
+    description: "Comma-separated list of repos to scope (e.g. kb-labs-cli,kb-labs-core)",
+    alias: "r"
+  },
+  yes: {
+    type: "boolean",
+    description: "Skip confirmation prompt",
+    default: false,
+    alias: "y"
+  },
+  json: {
+    type: "boolean",
+    description: "Output as JSON",
+    default: false
+  },
+  ttl: {
+    type: "number",
+    description: "npm registry cache TTL in hours (default: 24)",
+    default: 24
+  }
+};
+var statusFlags = {
+  json: {
+    type: "boolean",
+    description: "Output as JSON",
+    default: false
+  },
+  verbose: {
+    type: "boolean",
+    description: "Show all dependencies, not just cross-repo",
+    default: false,
+    alias: "v"
+  }
+};
+var planFlags = {
+  mode: {
+    type: "string",
+    description: "Target mode to plan for (defaults to opposite of current)",
+    choices: ["local", "npm", "auto"],
+    alias: "m"
+  },
+  repos: {
+    type: "string",
+    description: "Comma-separated list of repos to scope",
+    alias: "r"
+  },
+  json: {
+    type: "boolean",
+    description: "Output as JSON",
+    default: false
+  },
+  ttl: {
+    type: "number",
+    description: "npm registry cache TTL in hours (default: 24)",
+    default: 24
+  }
+};
+var freezeFlags = {
+  json: {
+    type: "boolean",
+    description: "Output as JSON",
+    default: false
+  }
+};
+var undoFlags = {
+  json: {
+    type: "boolean",
+    description: "Output as JSON",
+    default: false
+  }
+};
+var backupsFlags = {
+  restore: {
+    type: "string",
+    description: "Restore a specific backup by ID",
+    alias: "r"
+  },
+  json: {
+    type: "boolean",
+    description: "Output as JSON",
+    default: false
+  }
+};
+
+// src/index.ts
+var DEVLINK_CACHE_PREFIX = "devlink:";
+
+export { DEVLINK_CACHE_PREFIX, DependencyModeSchema, DevlinkBackupSchema, DevlinkModeSchema, DevlinkPlanItemSchema, DevlinkPlanSchema, DevlinkStateSchema, DevlinkStatusSchema, DiagnosticIssueSchema, PackageEntrySchema, PackageMapSchema, backupsFlags, freezeFlags, planFlags, statusFlags, switchFlags, undoFlags };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/flags.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { z } from 'zod';\n\n// ─── Mode ────────────────────────────────────────────────────────────────────\n\nexport const DevlinkModeSchema = z.enum(['local', 'npm', 'auto']);\nexport type DevlinkMode = z.infer<typeof DevlinkModeSchema>;\n\n// ─── Package Map ──────────────────────────────────────────────────────────────\n\nexport const PackageEntrySchema = z.object({\n  /** npm package name e.g. @kb-labs/core-platform */\n  name: z.string(),\n  /** Relative path for link: resolution e.g. ../kb-labs-core/packages/core-platform */\n  linkPath: z.string(),\n  /** npm version e.g. ^1.0.0 */\n  npmVersion: z.string(),\n  /** Source monorepo dir name e.g. kb-labs-core */\n  monorepo: z.string(),\n  /** Whether package.json has \"private\": true (stays as link: in npm mode) */\n  private: z.boolean().optional(),\n});\nexport type PackageEntry = z.infer<typeof PackageEntrySchema>;\n\nexport const PackageMapSchema = z.record(z.string(), PackageEntrySchema);\nexport type PackageMap = z.infer<typeof PackageMapSchema>;\n\n// ─── Plan ─────────────────────────────────────────────────────────────────────\n\nexport const DevlinkPlanItemSchema = z.object({\n  /** Absolute path to the package.json file to modify */\n  packageJsonPath: z.string(),\n  /** Relative path to packageJsonPath from repo root (for display) */\n  packageJsonRel: z.string(),\n  /** Owner monorepo e.g. kb-labs-cli */\n  monorepo: z.string(),\n  /** The dependency package being changed e.g. @kb-labs/core-platform */\n  depName: z.string(),\n  /** Current value in package.json */\n  from: z.string(),\n  /** New value to write */\n  to: z.string(),\n  /** Section: dependencies | devDependencies | peerDependencies */\n  section: z.enum(['dependencies', 'devDependencies', 'peerDependencies']),\n});\nexport type DevlinkPlanItem = z.infer<typeof DevlinkPlanItemSchema>;\n\nexport const DevlinkPlanSchema = z.object({\n  mode: DevlinkModeSchema,\n  items: z.array(DevlinkPlanItemSchema),\n  timestamp: z.string(),\n  /** Filtered to specific repos if --repos flag was used */\n  scopedRepos: z.array(z.string()).optional(),\n});\nexport type DevlinkPlan = z.infer<typeof DevlinkPlanSchema>;\n\n// ─── State ────────────────────────────────────────────────────────────────────\n\nexport const DevlinkStateSchema = z.object({\n  currentMode: DevlinkModeSchema.nullable(),\n  lastApplied: z.string().nullable(),\n  frozenAt: z.string().nullable(),\n});\nexport type DevlinkState = z.infer<typeof DevlinkStateSchema>;\n\n// ─── Backup ───────────────────────────────────────────────────────────────────\n\nexport const DevlinkBackupSchema = z.object({\n  id: z.string(),\n  timestamp: z.string(),\n  description: z.string(),\n  /** List of package.json paths that were backed up */\n  files: z.array(z.string()),\n  /** Mode that was active before backup was created */\n  modeAtBackup: DevlinkModeSchema.nullable(),\n});\nexport type DevlinkBackup = z.infer<typeof DevlinkBackupSchema>;\n\n// ─── Diagnostics ─────────────────────────────────────────────────────────────\n\nexport const DiagnosticIssueSchema = z.object({\n  type: z.enum(['broken-link', 'cross-repo-workspace', 'stale-lockfile', 'stale-workspace-yaml']),\n  severity: z.enum(['error', 'warning']),\n  file: z.string(),\n  dep: z.string().optional(),\n  message: z.string(),\n  fix: z.string(),\n});\nexport type DiagnosticIssue = z.infer<typeof DiagnosticIssueSchema>;\n\n// ─── Status ───────────────────────────────────────────────────────────────────\n\nexport const DependencyModeSchema = z.enum(['local', 'npm', 'workspace', 'mixed', 'unknown']);\nexport type DependencyMode = z.infer<typeof DependencyModeSchema>;\n\nexport const DevlinkStatusSchema = z.object({\n  currentMode: DevlinkModeSchema.nullable(),\n  lastApplied: z.string().nullable(),\n  linkCount: z.number(),\n  npmCount: z.number(),\n  workspaceCount: z.number(),\n  discrepancies: z.array(z.object({\n    packageJsonPath: z.string(),\n    depName: z.string(),\n    value: z.string(),\n    expected: z.string(),\n  })),\n});\nexport type DevlinkStatus = z.infer<typeof DevlinkStatusSchema>;\n","/**\n * Flag definitions for DevLink CLI commands.\n * Defined once here, reused in both manifest.ts and command handlers.\n */\n\nexport const switchFlags = {\n  mode: {\n    type: 'string' as const,\n    description: 'Linking mode: local (link:), npm (^version), auto',\n    choices: ['local', 'npm', 'auto'] as string[],\n    alias: 'm',\n    demandOption: true,\n  },\n  'dry-run': {\n    type: 'boolean' as const,\n    description: 'Preview changes without applying them',\n    default: false,\n    alias: 'd',\n  },\n  repos: {\n    type: 'string' as const,\n    description: 'Comma-separated list of repos to scope (e.g. kb-labs-cli,kb-labs-core)',\n    alias: 'r',\n  },\n  yes: {\n    type: 'boolean' as const,\n    description: 'Skip confirmation prompt',\n    default: false,\n    alias: 'y',\n  },\n  json: {\n    type: 'boolean' as const,\n    description: 'Output as JSON',\n    default: false,\n  },\n  ttl: {\n    type: 'number' as const,\n    description: 'npm registry cache TTL in hours (default: 24)',\n    default: 24,\n  },\n};\n\nexport const statusFlags = {\n  json: {\n    type: 'boolean' as const,\n    description: 'Output as JSON',\n    default: false,\n  },\n  verbose: {\n    type: 'boolean' as const,\n    description: 'Show all dependencies, not just cross-repo',\n    default: false,\n    alias: 'v',\n  },\n};\n\nexport const planFlags = {\n  mode: {\n    type: 'string' as const,\n    description: 'Target mode to plan for (defaults to opposite of current)',\n    choices: ['local', 'npm', 'auto'] as string[],\n    alias: 'm',\n  },\n  repos: {\n    type: 'string' as const,\n    description: 'Comma-separated list of repos to scope',\n    alias: 'r',\n  },\n  json: {\n    type: 'boolean' as const,\n    description: 'Output as JSON',\n    default: false,\n  },\n  ttl: {\n    type: 'number' as const,\n    description: 'npm registry cache TTL in hours (default: 24)',\n    default: 24,\n  },\n};\n\nexport const freezeFlags = {\n  json: {\n    type: 'boolean' as const,\n    description: 'Output as JSON',\n    default: false,\n  },\n};\n\nexport const undoFlags = {\n  json: {\n    type: 'boolean' as const,\n    description: 'Output as JSON',\n    default: false,\n  },\n};\n\nexport const backupsFlags = {\n  restore: {\n    type: 'string' as const,\n    description: 'Restore a specific backup by ID',\n    alias: 'r',\n  },\n  json: {\n    type: 'boolean' as const,\n    description: 'Output as JSON',\n    default: false,\n  },\n};\n\nexport type SwitchFlags = typeof switchFlags;\nexport type StatusFlags = typeof statusFlags;\nexport type PlanFlags = typeof planFlags;\nexport type FreezeFlags = typeof freezeFlags;\nexport type UndoFlags = typeof undoFlags;\nexport type BackupsFlags = typeof backupsFlags;\n","export * from './schema.js';\nexport * from './flags.js';\n\n/** Cache namespace prefix for devlink — used in manifest and npm checker */\nexport const DEVLINK_CACHE_PREFIX = 'devlink:' as const;\n"]}

package/dist/schema.d.ts

@@ -0,0 +1,263 @@
+import { z } from 'zod';
+
+declare const DevlinkModeSchema: z.ZodEnum<["local", "npm", "auto"]>;
+type DevlinkMode = z.infer<typeof DevlinkModeSchema>;
+declare const PackageEntrySchema: z.ZodObject<{
+    /** npm package name e.g. @kb-labs/core-platform */
+    name: z.ZodString;
+    /** Relative path for link: resolution e.g. ../kb-labs-core/packages/core-platform */
+    linkPath: z.ZodString;
+    /** npm version e.g. ^1.0.0 */
+    npmVersion: z.ZodString;
+    /** Source monorepo dir name e.g. kb-labs-core */
+    monorepo: z.ZodString;
+    /** Whether package.json has "private": true (stays as link: in npm mode) */
+    private: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    linkPath: string;
+    npmVersion: string;
+    monorepo: string;
+    private?: boolean | undefined;
+}, {
+    name: string;
+    linkPath: string;
+    npmVersion: string;
+    monorepo: string;
+    private?: boolean | undefined;
+}>;
+type PackageEntry = z.infer<typeof PackageEntrySchema>;
+declare const PackageMapSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    /** npm package name e.g. @kb-labs/core-platform */
+    name: z.ZodString;
+    /** Relative path for link: resolution e.g. ../kb-labs-core/packages/core-platform */
+    linkPath: z.ZodString;
+    /** npm version e.g. ^1.0.0 */
+    npmVersion: z.ZodString;
+    /** Source monorepo dir name e.g. kb-labs-core */
+    monorepo: z.ZodString;
+    /** Whether package.json has "private": true (stays as link: in npm mode) */
+    private: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    linkPath: string;
+    npmVersion: string;
+    monorepo: string;
+    private?: boolean | undefined;
+}, {
+    name: string;
+    linkPath: string;
+    npmVersion: string;
+    monorepo: string;
+    private?: boolean | undefined;
+}>>;
+type PackageMap = z.infer<typeof PackageMapSchema>;
+declare const DevlinkPlanItemSchema: z.ZodObject<{
+    /** Absolute path to the package.json file to modify */
+    packageJsonPath: z.ZodString;
+    /** Relative path to packageJsonPath from repo root (for display) */
+    packageJsonRel: z.ZodString;
+    /** Owner monorepo e.g. kb-labs-cli */
+    monorepo: z.ZodString;
+    /** The dependency package being changed e.g. @kb-labs/core-platform */
+    depName: z.ZodString;
+    /** Current value in package.json */
+    from: z.ZodString;
+    /** New value to write */
+    to: z.ZodString;
+    /** Section: dependencies | devDependencies | peerDependencies */
+    section: z.ZodEnum<["dependencies", "devDependencies", "peerDependencies"]>;
+}, "strip", z.ZodTypeAny, {
+    monorepo: string;
+    packageJsonPath: string;
+    packageJsonRel: string;
+    depName: string;
+    from: string;
+    to: string;
+    section: "dependencies" | "devDependencies" | "peerDependencies";
+}, {
+    monorepo: string;
+    packageJsonPath: string;
+    packageJsonRel: string;
+    depName: string;
+    from: string;
+    to: string;
+    section: "dependencies" | "devDependencies" | "peerDependencies";
+}>;
+type DevlinkPlanItem = z.infer<typeof DevlinkPlanItemSchema>;
+declare const DevlinkPlanSchema: z.ZodObject<{
+    mode: z.ZodEnum<["local", "npm", "auto"]>;
+    items: z.ZodArray<z.ZodObject<{
+        /** Absolute path to the package.json file to modify */
+        packageJsonPath: z.ZodString;
+        /** Relative path to packageJsonPath from repo root (for display) */
+        packageJsonRel: z.ZodString;
+        /** Owner monorepo e.g. kb-labs-cli */
+        monorepo: z.ZodString;
+        /** The dependency package being changed e.g. @kb-labs/core-platform */
+        depName: z.ZodString;
+        /** Current value in package.json */
+        from: z.ZodString;
+        /** New value to write */
+        to: z.ZodString;
+        /** Section: dependencies | devDependencies | peerDependencies */
+        section: z.ZodEnum<["dependencies", "devDependencies", "peerDependencies"]>;
+    }, "strip", z.ZodTypeAny, {
+        monorepo: string;
+        packageJsonPath: string;
+        packageJsonRel: string;
+        depName: string;
+        from: string;
+        to: string;
+        section: "dependencies" | "devDependencies" | "peerDependencies";
+    }, {
+        monorepo: string;
+        packageJsonPath: string;
+        packageJsonRel: string;
+        depName: string;
+        from: string;
+        to: string;
+        section: "dependencies" | "devDependencies" | "peerDependencies";
+    }>, "many">;
+    timestamp: z.ZodString;
+    /** Filtered to specific repos if --repos flag was used */
+    scopedRepos: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    mode: "local" | "npm" | "auto";
+    items: {
+        monorepo: string;
+        packageJsonPath: string;
+        packageJsonRel: string;
+        depName: string;
+        from: string;
+        to: string;
+        section: "dependencies" | "devDependencies" | "peerDependencies";
+    }[];
+    timestamp: string;
+    scopedRepos?: string[] | undefined;
+}, {
+    mode: "local" | "npm" | "auto";
+    items: {
+        monorepo: string;
+        packageJsonPath: string;
+        packageJsonRel: string;
+        depName: string;
+        from: string;
+        to: string;
+        section: "dependencies" | "devDependencies" | "peerDependencies";
+    }[];
+    timestamp: string;
+    scopedRepos?: string[] | undefined;
+}>;
+type DevlinkPlan = z.infer<typeof DevlinkPlanSchema>;
+declare const DevlinkStateSchema: z.ZodObject<{
+    currentMode: z.ZodNullable<z.ZodEnum<["local", "npm", "auto"]>>;
+    lastApplied: z.ZodNullable<z.ZodString>;
+    frozenAt: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    currentMode: "local" | "npm" | "auto" | null;
+    lastApplied: string | null;
+    frozenAt: string | null;
+}, {
+    currentMode: "local" | "npm" | "auto" | null;
+    lastApplied: string | null;
+    frozenAt: string | null;
+}>;
+type DevlinkState = z.infer<typeof DevlinkStateSchema>;
+declare const DevlinkBackupSchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodString;
+    description: z.ZodString;
+    /** List of package.json paths that were backed up */
+    files: z.ZodArray<z.ZodString, "many">;
+    /** Mode that was active before backup was created */
+    modeAtBackup: z.ZodNullable<z.ZodEnum<["local", "npm", "auto"]>>;
+}, "strip", z.ZodTypeAny, {
+    timestamp: string;
+    id: string;
+    description: string;
+    files: string[];
+    modeAtBackup: "local" | "npm" | "auto" | null;
+}, {
+    timestamp: string;
+    id: string;
+    description: string;
+    files: string[];
+    modeAtBackup: "local" | "npm" | "auto" | null;
+}>;
+type DevlinkBackup = z.infer<typeof DevlinkBackupSchema>;
+declare const DiagnosticIssueSchema: z.ZodObject<{
+    type: z.ZodEnum<["broken-link", "cross-repo-workspace", "stale-lockfile", "stale-workspace-yaml"]>;
+    severity: z.ZodEnum<["error", "warning"]>;
+    file: z.ZodString;
+    dep: z.ZodOptional<z.ZodString>;
+    message: z.ZodString;
+    fix: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    type: "broken-link" | "cross-repo-workspace" | "stale-lockfile" | "stale-workspace-yaml";
+    severity: "error" | "warning";
+    file: string;
+    fix: string;
+    dep?: string | undefined;
+}, {
+    message: string;
+    type: "broken-link" | "cross-repo-workspace" | "stale-lockfile" | "stale-workspace-yaml";
+    severity: "error" | "warning";
+    file: string;
+    fix: string;
+    dep?: string | undefined;
+}>;
+type DiagnosticIssue = z.infer<typeof DiagnosticIssueSchema>;
+declare const DependencyModeSchema: z.ZodEnum<["local", "npm", "workspace", "mixed", "unknown"]>;
+type DependencyMode = z.infer<typeof DependencyModeSchema>;
+declare const DevlinkStatusSchema: z.ZodObject<{
+    currentMode: z.ZodNullable<z.ZodEnum<["local", "npm", "auto"]>>;
+    lastApplied: z.ZodNullable<z.ZodString>;
+    linkCount: z.ZodNumber;
+    npmCount: z.ZodNumber;
+    workspaceCount: z.ZodNumber;
+    discrepancies: z.ZodArray<z.ZodObject<{
+        packageJsonPath: z.ZodString;
+        depName: z.ZodString;
+        value: z.ZodString;
+        expected: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        expected: string;
+        packageJsonPath: string;
+        depName: string;
+    }, {
+        value: string;
+        expected: string;
+        packageJsonPath: string;
+        depName: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    currentMode: "local" | "npm" | "auto" | null;
+    lastApplied: string | null;
+    linkCount: number;
+    npmCount: number;
+    workspaceCount: number;
+    discrepancies: {
+        value: string;
+        expected: string;
+        packageJsonPath: string;
+        depName: string;
+    }[];
+}, {
+    currentMode: "local" | "npm" | "auto" | null;
+    lastApplied: string | null;
+    linkCount: number;
+    npmCount: number;
+    workspaceCount: number;
+    discrepancies: {
+        value: string;
+        expected: string;
+        packageJsonPath: string;
+        depName: string;
+    }[];
+}>;
+type DevlinkStatus = z.infer<typeof DevlinkStatusSchema>;
+
+export { type DependencyMode, DependencyModeSchema, type DevlinkBackup, DevlinkBackupSchema, type DevlinkMode, DevlinkModeSchema, type DevlinkPlan, type DevlinkPlanItem, DevlinkPlanItemSchema, DevlinkPlanSchema, type DevlinkState, DevlinkStateSchema, type DevlinkStatus, DevlinkStatusSchema, type DiagnosticIssue, DiagnosticIssueSchema, type PackageEntry, PackageEntrySchema, type PackageMap, PackageMapSchema };

package/dist/schema.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+
+// src/schema.ts
+var DevlinkModeSchema = z.enum(["local", "npm", "auto"]);
+var PackageEntrySchema = z.object({
+  /** npm package name e.g. @kb-labs/core-platform */
+  name: z.string(),
+  /** Relative path for link: resolution e.g. ../kb-labs-core/packages/core-platform */
+  linkPath: z.string(),
+  /** npm version e.g. ^1.0.0 */
+  npmVersion: z.string(),
+  /** Source monorepo dir name e.g. kb-labs-core */
+  monorepo: z.string(),
+  /** Whether package.json has "private": true (stays as link: in npm mode) */
+  private: z.boolean().optional()
+});
+var PackageMapSchema = z.record(z.string(), PackageEntrySchema);
+var DevlinkPlanItemSchema = z.object({
+  /** Absolute path to the package.json file to modify */
+  packageJsonPath: z.string(),
+  /** Relative path to packageJsonPath from repo root (for display) */
+  packageJsonRel: z.string(),
+  /** Owner monorepo e.g. kb-labs-cli */
+  monorepo: z.string(),
+  /** The dependency package being changed e.g. @kb-labs/core-platform */
+  depName: z.string(),
+  /** Current value in package.json */
+  from: z.string(),
+  /** New value to write */
+  to: z.string(),
+  /** Section: dependencies | devDependencies | peerDependencies */
+  section: z.enum(["dependencies", "devDependencies", "peerDependencies"])
+});
+var DevlinkPlanSchema = z.object({
+  mode: DevlinkModeSchema,
+  items: z.array(DevlinkPlanItemSchema),
+  timestamp: z.string(),
+  /** Filtered to specific repos if --repos flag was used */
+  scopedRepos: z.array(z.string()).optional()
+});
+var DevlinkStateSchema = z.object({
+  currentMode: DevlinkModeSchema.nullable(),
+  lastApplied: z.string().nullable(),
+  frozenAt: z.string().nullable()
+});
+var DevlinkBackupSchema = z.object({
+  id: z.string(),
+  timestamp: z.string(),
+  description: z.string(),
+  /** List of package.json paths that were backed up */
+  files: z.array(z.string()),
+  /** Mode that was active before backup was created */
+  modeAtBackup: DevlinkModeSchema.nullable()
+});
+var DiagnosticIssueSchema = z.object({
+  type: z.enum(["broken-link", "cross-repo-workspace", "stale-lockfile", "stale-workspace-yaml"]),
+  severity: z.enum(["error", "warning"]),
+  file: z.string(),
+  dep: z.string().optional(),
+  message: z.string(),
+  fix: z.string()
+});
+var DependencyModeSchema = z.enum(["local", "npm", "workspace", "mixed", "unknown"]);
+var DevlinkStatusSchema = z.object({
+  currentMode: DevlinkModeSchema.nullable(),
+  lastApplied: z.string().nullable(),
+  linkCount: z.number(),
+  npmCount: z.number(),
+  workspaceCount: z.number(),
+  discrepancies: z.array(z.object({
+    packageJsonPath: z.string(),
+    depName: z.string(),
+    value: z.string(),
+    expected: z.string()
+  }))
+});
+
+export { DependencyModeSchema, DevlinkBackupSchema, DevlinkModeSchema, DevlinkPlanItemSchema, DevlinkPlanSchema, DevlinkStateSchema, DevlinkStatusSchema, DiagnosticIssueSchema, PackageEntrySchema, PackageMapSchema };
+//# sourceMappingURL=schema.js.map
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts"],"names":[],"mappings":"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","file":"schema.js","sourcesContent":["import { z } from 'zod';\n\n// ─── Mode ────────────────────────────────────────────────────────────────────\n\nexport const DevlinkModeSchema = z.enum(['local', 'npm', 'auto']);\nexport type DevlinkMode = z.infer<typeof DevlinkModeSchema>;\n\n// ─── Package Map ──────────────────────────────────────────────────────────────\n\nexport const PackageEntrySchema = z.object({\n  /** npm package name e.g. @kb-labs/core-platform */\n  name: z.string(),\n  /** Relative path for link: resolution e.g. ../kb-labs-core/packages/core-platform */\n  linkPath: z.string(),\n  /** npm version e.g. ^1.0.0 */\n  npmVersion: z.string(),\n  /** Source monorepo dir name e.g. kb-labs-core */\n  monorepo: z.string(),\n  /** Whether package.json has \"private\": true (stays as link: in npm mode) */\n  private: z.boolean().optional(),\n});\nexport type PackageEntry = z.infer<typeof PackageEntrySchema>;\n\nexport const PackageMapSchema = z.record(z.string(), PackageEntrySchema);\nexport type PackageMap = z.infer<typeof PackageMapSchema>;\n\n// ─── Plan ─────────────────────────────────────────────────────────────────────\n\nexport const DevlinkPlanItemSchema = z.object({\n  /** Absolute path to the package.json file to modify */\n  packageJsonPath: z.string(),\n  /** Relative path to packageJsonPath from repo root (for display) */\n  packageJsonRel: z.string(),\n  /** Owner monorepo e.g. kb-labs-cli */\n  monorepo: z.string(),\n  /** The dependency package being changed e.g. @kb-labs/core-platform */\n  depName: z.string(),\n  /** Current value in package.json */\n  from: z.string(),\n  /** New value to write */\n  to: z.string(),\n  /** Section: dependencies | devDependencies | peerDependencies */\n  section: z.enum(['dependencies', 'devDependencies', 'peerDependencies']),\n});\nexport type DevlinkPlanItem = z.infer<typeof DevlinkPlanItemSchema>;\n\nexport const DevlinkPlanSchema = z.object({\n  mode: DevlinkModeSchema,\n  items: z.array(DevlinkPlanItemSchema),\n  timestamp: z.string(),\n  /** Filtered to specific repos if --repos flag was used */\n  scopedRepos: z.array(z.string()).optional(),\n});\nexport type DevlinkPlan = z.infer<typeof DevlinkPlanSchema>;\n\n// ─── State ────────────────────────────────────────────────────────────────────\n\nexport const DevlinkStateSchema = z.object({\n  currentMode: DevlinkModeSchema.nullable(),\n  lastApplied: z.string().nullable(),\n  frozenAt: z.string().nullable(),\n});\nexport type DevlinkState = z.infer<typeof DevlinkStateSchema>;\n\n// ─── Backup ───────────────────────────────────────────────────────────────────\n\nexport const DevlinkBackupSchema = z.object({\n  id: z.string(),\n  timestamp: z.string(),\n  description: z.string(),\n  /** List of package.json paths that were backed up */\n  files: z.array(z.string()),\n  /** Mode that was active before backup was created */\n  modeAtBackup: DevlinkModeSchema.nullable(),\n});\nexport type DevlinkBackup = z.infer<typeof DevlinkBackupSchema>;\n\n// ─── Diagnostics ─────────────────────────────────────────────────────────────\n\nexport const DiagnosticIssueSchema = z.object({\n  type: z.enum(['broken-link', 'cross-repo-workspace', 'stale-lockfile', 'stale-workspace-yaml']),\n  severity: z.enum(['error', 'warning']),\n  file: z.string(),\n  dep: z.string().optional(),\n  message: z.string(),\n  fix: z.string(),\n});\nexport type DiagnosticIssue = z.infer<typeof DiagnosticIssueSchema>;\n\n// ─── Status ───────────────────────────────────────────────────────────────────\n\nexport const DependencyModeSchema = z.enum(['local', 'npm', 'workspace', 'mixed', 'unknown']);\nexport type DependencyMode = z.infer<typeof DependencyModeSchema>;\n\nexport const DevlinkStatusSchema = z.object({\n  currentMode: DevlinkModeSchema.nullable(),\n  lastApplied: z.string().nullable(),\n  linkCount: z.number(),\n  npmCount: z.number(),\n  workspaceCount: z.number(),\n  discrepancies: z.array(z.object({\n    packageJsonPath: z.string(),\n    depName: z.string(),\n    value: z.string(),\n    expected: z.string(),\n  })),\n});\nexport type DevlinkStatus = z.infer<typeof DevlinkStatusSchema>;\n"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@kb-labs/devlink-contracts",
+  "version": "1.5.0",
+  "type": "module",
+  "description": "Contracts package for DevLink plugin — types, Zod schemas, flags.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./schema": {
+      "import": "./dist/schema.js",
+      "types": "./dist/schema.d.ts"
+    },
+    "./dist/*": "./dist/*"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
+    "@types/node": "^24.3.3",
+    "eslint": "^9",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}