@duypham93/openkit 0.2.0

package/src/global/workspace-state.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { getWorkspacePaths } from './paths.js';
+
+const WORKSPACE_STATE_SCHEMA = 'openkit/workspace-state@1';
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function createWorkspaceMeta({ projectRoot, workspaceId, kitVersion = '0.1.0', profile = 'openkit' }) {
+  return {
+    schema: WORKSPACE_STATE_SCHEMA,
+    stateVersion: 1,
+    projectRoot,
+    workspaceId,
+    profile,
+    kitVersion,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+export function ensureWorkspaceBootstrap(options = {}) {
+  const paths = getWorkspacePaths(options);
+
+  fs.mkdirSync(paths.opencodeDir, { recursive: true });
+  fs.mkdirSync(paths.workItemsDir, { recursive: true });
+
+  if (!fs.existsSync(paths.workspaceMetaPath)) {
+    writeJson(
+      paths.workspaceMetaPath,
+      createWorkspaceMeta({
+        projectRoot: paths.projectRoot,
+        workspaceId: paths.workspaceId,
+      }),
+    );
+  }
+
+  if (!fs.existsSync(paths.workItemIndexPath)) {
+    writeJson(paths.workItemIndexPath, {
+      active_work_item_id: null,
+      work_items: [],
+    });
+  }
+
+  return paths;
+}
+
+export function readWorkspaceMeta(options = {}) {
+  const paths = ensureWorkspaceBootstrap(options);
+  return {
+    paths,
+    meta: readJson(paths.workspaceMetaPath),
+    index: readJson(paths.workItemIndexPath),
+  };
+}

package/src/install/asset-manifest.js

@@ -0,0 +1,284 @@
+import fs from "node:fs"
+import path from "node:path"
+
+const OPENKIT_OPENCODE_BUNDLED_ASSETS = [
+  {
+    id: "opencode.bundle.readme",
+    assetClass: "bundle-metadata",
+    sourcePath: "assets/install-bundle/opencode/README.md",
+    bundledPath: "assets/install-bundle/opencode/README.md",
+  },
+  {
+    id: "opencode.agent.ArchitectAgent",
+    assetClass: "agents",
+    sourcePath: "agents/architect-agent.md",
+    bundledPath: "assets/install-bundle/opencode/agents/ArchitectAgent.md",
+  },
+  {
+    id: "opencode.agent.BAAgent",
+    assetClass: "agents",
+    sourcePath: "agents/ba-agent.md",
+    bundledPath: "assets/install-bundle/opencode/agents/BAAgent.md",
+  },
+  {
+    id: "opencode.agent.CodeReviewer",
+    assetClass: "agents",
+    sourcePath: "agents/code-reviewer.md",
+    bundledPath: "assets/install-bundle/opencode/agents/CodeReviewer.md",
+  },
+  {
+    id: "opencode.agent.FullstackAgent",
+    assetClass: "agents",
+    sourcePath: "agents/fullstack-agent.md",
+    bundledPath: "assets/install-bundle/opencode/agents/FullstackAgent.md",
+  },
+  {
+    id: "opencode.agent.MasterOrchestrator",
+    assetClass: "agents",
+    sourcePath: "agents/master-orchestrator.md",
+    bundledPath: "assets/install-bundle/opencode/agents/MasterOrchestrator.md",
+  },
+  {
+    id: "opencode.agent.PMAgent",
+    assetClass: "agents",
+    sourcePath: "agents/pm-agent.md",
+    bundledPath: "assets/install-bundle/opencode/agents/PMAgent.md",
+  },
+  {
+    id: "opencode.agent.QAAgent",
+    assetClass: "agents",
+    sourcePath: "agents/qa-agent.md",
+    bundledPath: "assets/install-bundle/opencode/agents/QAAgent.md",
+  },
+  {
+    id: "opencode.agent.TechLeadAgent",
+    assetClass: "agents",
+    sourcePath: "agents/tech-lead-agent.md",
+    bundledPath: "assets/install-bundle/opencode/agents/TechLeadAgent.md",
+  },
+  {
+    id: "opencode.command.brainstorm",
+    assetClass: "commands",
+    sourcePath: "commands/brainstorm.md",
+    bundledPath: "assets/install-bundle/opencode/commands/brainstorm.md",
+  },
+  {
+    id: "opencode.command.delivery",
+    assetClass: "commands",
+    sourcePath: "commands/delivery.md",
+    bundledPath: "assets/install-bundle/opencode/commands/delivery.md",
+  },
+  {
+    id: "opencode.command.execute-plan",
+    assetClass: "commands",
+    sourcePath: "commands/execute-plan.md",
+    bundledPath: "assets/install-bundle/opencode/commands/execute-plan.md",
+  },
+  {
+    id: "opencode.command.migrate",
+    assetClass: "commands",
+    sourcePath: "commands/migrate.md",
+    bundledPath: "assets/install-bundle/opencode/commands/migrate.md",
+  },
+  {
+    id: "opencode.command.quick-task",
+    assetClass: "commands",
+    sourcePath: "commands/quick-task.md",
+    bundledPath: "assets/install-bundle/opencode/commands/quick-task.md",
+  },
+  {
+    id: "opencode.command.task",
+    assetClass: "commands",
+    sourcePath: "commands/task.md",
+    bundledPath: "assets/install-bundle/opencode/commands/task.md",
+  },
+  {
+    id: "opencode.command.write-plan",
+    assetClass: "commands",
+    sourcePath: "commands/write-plan.md",
+    bundledPath: "assets/install-bundle/opencode/commands/write-plan.md",
+  },
+  {
+    id: "opencode.context.lane-selection",
+    assetClass: "context",
+    sourcePath: "context/core/lane-selection.md",
+    bundledPath: "assets/install-bundle/opencode/context/core/lane-selection.md",
+  },
+  {
+    id: "opencode.skill.brainstorming",
+    assetClass: "skills",
+    sourcePath: "skills/brainstorming/SKILL.md",
+    bundledPath: "assets/install-bundle/opencode/skills/brainstorming/SKILL.md",
+  },
+  {
+    id: "opencode.skill.code-review",
+    assetClass: "skills",
+    sourcePath: "skills/code-review/SKILL.md",
+    bundledPath: "assets/install-bundle/opencode/skills/code-review/SKILL.md",
+  },
+  {
+    id: "opencode.skill.subagent-driven-development",
+    assetClass: "skills",
+    sourcePath: "skills/subagent-driven-development/SKILL.md",
+    bundledPath: "assets/install-bundle/opencode/skills/subagent-driven-development/SKILL.md",
+  },
+  {
+    id: "opencode.skill.systematic-debugging",
+    assetClass: "skills",
+    sourcePath: "skills/systematic-debugging/SKILL.md",
+    bundledPath: "assets/install-bundle/opencode/skills/systematic-debugging/SKILL.md",
+  },
+  {
+    id: "opencode.skill.test-driven-development",
+    assetClass: "skills",
+    sourcePath: "skills/test-driven-development/SKILL.md",
+    bundledPath: "assets/install-bundle/opencode/skills/test-driven-development/SKILL.md",
+  },
+  {
+    id: "opencode.skill.using-skills",
+    assetClass: "skills",
+    sourcePath: "skills/using-skills/SKILL.md",
+    bundledPath: "assets/install-bundle/opencode/skills/using-skills/SKILL.md",
+  },
+  {
+    id: "opencode.skill.verification-before-completion",
+    assetClass: "skills",
+    sourcePath: "skills/verification-before-completion/SKILL.md",
+    bundledPath: "assets/install-bundle/opencode/skills/verification-before-completion/SKILL.md",
+  },
+  {
+    id: "opencode.skill.writing-plans",
+    assetClass: "skills",
+    sourcePath: "skills/writing-plans/SKILL.md",
+    bundledPath: "assets/install-bundle/opencode/skills/writing-plans/SKILL.md",
+  },
+  {
+    id: "opencode.skill.writing-specs",
+    assetClass: "skills",
+    sourcePath: "skills/writing-specs/SKILL.md",
+    bundledPath: "assets/install-bundle/opencode/skills/writing-specs/SKILL.md",
+  },
+]
+
+export const OPENKIT_ASSET_MANIFEST = {
+  schema: "openkit/asset-manifest@1",
+  manifestVersion: 1,
+  bundle: {
+    namespace: "openkit",
+    profile: "openkit-global-install",
+    phase: 1,
+    derivedFrom: ["agents/", "commands/", "skills/"],
+    includedAssetClasses: ["agents", "commands", "context", "skills"],
+    deferredAssetClasses: ["plugins", "package.json"],
+    collisionPolicy: {
+      installNamespace: "openkit",
+      assetIdPrefix: "opencode",
+      onCollision: "fail-closed-and-require-explicit-mapping",
+      rationale:
+        "Phase 1 ships an explicit namespaced bundle instead of overwriting unrelated OpenCode-native assets.",
+    },
+    assets: OPENKIT_OPENCODE_BUNDLED_ASSETS,
+  },
+  assets: [
+    {
+      id: "runtime.opencode-manifest",
+      path: "opencode.json",
+      kind: "template",
+      templatePath: "assets/opencode.json.template",
+      phase: 1,
+      required: true,
+      adoptionAllowed: true,
+      description: "Managed install entrypoint manifest for OpenKit installs.",
+    },
+    {
+      id: "runtime.install-state",
+      path: ".openkit/openkit-install.json",
+      kind: "template",
+      templatePath: "assets/openkit-install.json.template",
+      phase: 1,
+      required: true,
+      adoptionAllowed: false,
+      description: "OpenKit-managed install state persisted in the target repository.",
+    },
+  ],
+}
+
+export function listManagedAssetIds() {
+  return OPENKIT_ASSET_MANIFEST.assets.map((asset) => asset.id)
+}
+
+export function listBundledAssetIds() {
+  return OPENKIT_ASSET_MANIFEST.bundle.assets.map((asset) => asset.id)
+}
+
+export function getManagedAsset(assetId) {
+  return OPENKIT_ASSET_MANIFEST.assets.find((asset) => asset.id === assetId) ?? null
+}
+
+export function validateBundledAssetFiles(projectRoot) {
+  const bundleRoot = path.join(projectRoot, "assets", "install-bundle", "opencode")
+  const missingFiles = []
+  const mismatchedFiles = []
+
+  for (const asset of OPENKIT_ASSET_MANIFEST.bundle.assets) {
+    const sourcePath = path.join(projectRoot, asset.sourcePath)
+    const bundledPath = path.join(projectRoot, asset.bundledPath)
+    const hasSourceFile = fs.existsSync(sourcePath)
+    const hasBundledFile = fs.existsSync(bundledPath)
+
+    if (!hasSourceFile) {
+      missingFiles.push(asset.sourcePath)
+    }
+
+    if (!hasBundledFile) {
+      missingFiles.push(asset.bundledPath)
+    }
+
+    if (hasSourceFile && hasBundledFile) {
+      const sourceContents = fs.readFileSync(sourcePath, "utf8")
+      const bundledContents = fs.readFileSync(bundledPath, "utf8")
+
+      if (sourceContents !== bundledContents) {
+        mismatchedFiles.push({
+          id: asset.id,
+          sourcePath: asset.sourcePath,
+          bundledPath: asset.bundledPath,
+        })
+      }
+    }
+  }
+
+  const bundledFiles = []
+
+  function collectFiles(currentPath) {
+    for (const entry of fs.readdirSync(currentPath, { withFileTypes: true })) {
+      const entryPath = path.join(currentPath, entry.name)
+
+      if (entry.isDirectory()) {
+        collectFiles(entryPath)
+        continue
+      }
+
+      bundledFiles.push(path.relative(projectRoot, entryPath))
+    }
+  }
+
+  if (fs.existsSync(bundleRoot)) {
+    collectFiles(bundleRoot)
+  }
+
+  const expectedBundledFiles = new Set(
+    OPENKIT_ASSET_MANIFEST.bundle.assets.map((asset) => asset.bundledPath),
+  )
+
+  const extraBundledFiles = bundledFiles.filter((filePath) => !expectedBundledFiles.has(filePath))
+
+  return {
+    missingFiles,
+    mismatchedFiles,
+    bundleFileCount: OPENKIT_ASSET_MANIFEST.bundle.assets.length,
+    expectedBundledFiles: [...expectedBundledFiles],
+    actualBundledFiles: bundledFiles,
+    extraBundledFiles,
+  }
+}

package/src/install/conflicts.js

@@ -0,0 +1,43 @@
+export function createMaterializationConflict({
+  assetId,
+  path,
+  field,
+  reason,
+  currentValue,
+  desiredValue,
+  resolution = "manual-review-required",
+}) {
+  const conflict = {
+    assetId,
+    path,
+    reason,
+    resolution,
+  }
+
+  if (field !== undefined) {
+    conflict.field = field
+  }
+
+  if (currentValue !== undefined) {
+    conflict.currentValue = currentValue
+  }
+
+  if (desiredValue !== undefined) {
+    conflict.desiredValue = desiredValue
+  }
+
+  return conflict
+}
+
+export function qualifyMergeConflicts(mergeConflicts, assetId, assetPath) {
+  return mergeConflicts.map((conflict) =>
+    createMaterializationConflict({
+      assetId,
+      path: assetPath,
+      field: conflict.field,
+      reason: conflict.reason,
+      currentValue: conflict.currentValue,
+      desiredValue: conflict.desiredValue,
+    }),
+  )
+}

package/src/install/discovery.js

@@ -0,0 +1,138 @@
+import fs from "node:fs"
+import path from "node:path"
+
+function fileExists(filePath) {
+  return fs.existsSync(filePath)
+}
+
+function safeReadJson(filePath) {
+  if (!fileExists(filePath)) {
+    return {
+      exists: false,
+      value: null,
+      malformed: false,
+    }
+  }
+
+  try {
+    return {
+      exists: true,
+      value: JSON.parse(fs.readFileSync(filePath, "utf8")),
+      malformed: false,
+    }
+  } catch {
+    return {
+      exists: true,
+      value: null,
+      malformed: true,
+    }
+  }
+}
+
+function classifyProjectShape({
+  hasRuntimeManifest,
+  hasRootInstallEntrypoint,
+  hasInstallManifest,
+  hasRegistry,
+  installManifest,
+  registry,
+  malformedMetadata,
+}) {
+  const notes = []
+
+  if (malformedMetadata.installManifest) {
+    notes.push("Install manifest metadata is malformed and could not be parsed.")
+  }
+
+  if (malformedMetadata.registry) {
+    notes.push("Registry metadata is malformed and could not be parsed.")
+  }
+
+  if (hasRuntimeManifest && hasRootInstallEntrypoint) {
+    return {
+      classification: "mixed-install-surfaces",
+      notes: [
+        ...notes,
+        "Detected both repository-local runtime and root install entrypoint surfaces; treat install adoption as mixed and review manually.",
+      ],
+    }
+  }
+
+  const installMode = installManifest?.installation?.mode
+  const emergingSurface = registry?.kit?.productSurface?.emerging
+
+  if (
+    hasRuntimeManifest &&
+    hasInstallManifest &&
+    hasRegistry &&
+    installMode === "additive-non-destructive" &&
+    emergingSurface === "global-openkit-install"
+  ) {
+    return {
+      classification: "openkit-additive-local-metadata",
+      notes,
+    }
+  }
+
+  if (hasRuntimeManifest && !hasInstallManifest && !hasRegistry) {
+    return {
+      classification: "opencode-runtime-only",
+      notes,
+    }
+  }
+
+  if (!hasRuntimeManifest && !hasRootInstallEntrypoint) {
+    return {
+      classification: "unknown",
+      notes: [...notes, "No recognized runtime manifest or install entrypoint was found."],
+    }
+  }
+
+  return {
+    classification: "unclassified",
+    notes: [...notes, "Detected a partial or unsupported runtime surface combination."],
+  }
+}
+
+export function discoverProjectShape(projectRoot) {
+  const runtimeManifestPath = path.join(projectRoot, ".opencode", "opencode.json")
+  const rootInstallEntrypointPath = path.join(projectRoot, "opencode.json")
+  const installManifestPath = path.join(projectRoot, ".opencode", "install-manifest.json")
+  const registryPath = path.join(projectRoot, "registry.json")
+
+  const hasRuntimeManifest = fileExists(runtimeManifestPath)
+  const hasRootInstallEntrypoint = fileExists(rootInstallEntrypointPath)
+  const hasInstallManifest = fileExists(installManifestPath)
+  const hasRegistry = fileExists(registryPath)
+
+  const installManifestResult = safeReadJson(installManifestPath)
+  const registryResult = safeReadJson(registryPath)
+  const malformedMetadata = {
+    installManifest: installManifestResult.malformed,
+    registry: registryResult.malformed,
+  }
+  const classification = classifyProjectShape({
+    hasRuntimeManifest,
+    hasRootInstallEntrypoint,
+    hasInstallManifest,
+    hasRegistry,
+    installManifest: installManifestResult.value,
+    registry: registryResult.value,
+    malformedMetadata,
+  })
+
+  return {
+    projectRoot,
+    runtimeManifestPath,
+    rootInstallEntrypointPath,
+    installManifestPath,
+    registryPath,
+    hasRuntimeManifest,
+    hasRootInstallEntrypoint,
+    hasInstallManifest,
+    hasRegistry,
+    malformedMetadata,
+    classification: classification.classification,
+    notes: classification.notes,
+  }
+}

package/src/install/install-state.js

@@ -0,0 +1,136 @@
+export const INSTALL_STATE_SCHEMA = "openkit/install-state@1"
+
+const MANAGED_STATUSES = new Set(["managed", "materialized"])
+const ISO_8601_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/
+
+function createIsoTimestamp(now = new Date()) {
+  return now.toISOString()
+}
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0
+}
+
+function isIsoTimestamp(value) {
+  return isNonEmptyString(value) && ISO_8601_TIMESTAMP_PATTERN.test(value)
+}
+
+function normalizeArray(value) {
+  return Array.isArray(value) ? value : []
+}
+
+function isArray(value) {
+  return Array.isArray(value)
+}
+
+export function createInstallState({
+  kitVersion = "0.1.0",
+  profile = "openkit-core",
+  managedAssets = [],
+  adoptedAssets = [],
+  warnings = [],
+  conflicts = [],
+  now,
+} = {}) {
+  return {
+    schema: INSTALL_STATE_SCHEMA,
+    stateVersion: 1,
+    kit: {
+      name: "OpenKit",
+      version: kitVersion,
+    },
+    installation: {
+      profile,
+      status: "installed",
+      installedAt: createIsoTimestamp(now),
+    },
+    assets: {
+      managed: normalizeArray(managedAssets),
+      adopted: normalizeArray(adoptedAssets),
+    },
+    warnings: normalizeArray(warnings),
+    conflicts: normalizeArray(conflicts),
+  }
+}
+
+export function validateInstallState(state) {
+  const errors = []
+
+  if (!state || typeof state !== "object") {
+    return ["install state must be an object"]
+  }
+
+  if (state.schema !== INSTALL_STATE_SCHEMA) {
+    errors.push(`schema must be '${INSTALL_STATE_SCHEMA}'`)
+  }
+
+  if (state.stateVersion !== 1) {
+    errors.push("stateVersion must be 1")
+  }
+
+  if (!isNonEmptyString(state.kit?.name)) {
+    errors.push("kit.name must be a non-empty string")
+  }
+
+  if (!isNonEmptyString(state.kit?.version)) {
+    errors.push("kit.version must be a non-empty string")
+  }
+
+  if (!isNonEmptyString(state.installation?.profile)) {
+    errors.push("installation.profile must be a non-empty string")
+  }
+
+  if (state.installation?.status !== "installed") {
+    errors.push("installation.status must be 'installed'")
+  }
+
+  if (!isIsoTimestamp(state.installation?.installedAt)) {
+    errors.push("installation.installedAt must be an ISO-8601 timestamp")
+  }
+
+  if (!isArray(state.assets?.managed)) {
+    errors.push("assets.managed must be an array")
+  } else {
+    state.assets.managed.forEach((asset, index) => {
+      if (!isNonEmptyString(asset?.path)) {
+        errors.push(`assets.managed[${index}].path must be a non-empty string`)
+      }
+
+      if (!MANAGED_STATUSES.has(asset?.status)) {
+        errors.push(`assets.managed[${index}].status must be one of: managed, materialized`)
+      }
+    })
+  }
+
+  if (!isArray(state.assets?.adopted)) {
+    errors.push("assets.adopted must be an array")
+  } else {
+    state.assets.adopted.forEach((asset, index) => {
+      if (asset?.status !== "adopted") {
+        errors.push(`assets.adopted[${index}].status must be 'adopted'`)
+      }
+    })
+  }
+
+  if (!isArray(state.warnings)) {
+    errors.push("warnings must be an array")
+  } else {
+    state.warnings.forEach((warning, index) => {
+      if (!isNonEmptyString(warning?.code)) {
+        errors.push(`warnings[${index}].code must be a non-empty string`)
+      }
+    })
+  }
+
+  if (!isArray(state.conflicts)) {
+    errors.push("conflicts must be an array")
+  } else {
+    state.conflicts.forEach((conflict, index) => {
+      if (!isNonEmptyString(conflict?.reason)) {
+        errors.push(`conflicts[${index}].reason must be a non-empty string`)
+      }
+    })
+  }
+
+  return errors
+}