@topogram/cli 0.3.78 → 0.3.80

package/src/import/provenance.js

@@ -4,7 +4,7 @@ import path from "node:path";
 
 import { listFilesRecursive, relativeTo } from "./core/shared.js";
 
-export const TOPOGRAM_IMPORT_FILE = ".topogram-import.json";
+export const TOPOGRAM_IMPORT_FILE = ".topogram-extract.json";
 
 function fileHash(filePath) {
   const bytes = fs.readFileSync(filePath);
@@ -42,22 +42,23 @@ export function writeTopogramImportRecord(projectRoot, input) {
   const timestamp = input.timestamp || new Date().toISOString();
   const record = {
     version: "0.1",
-    kind: "brownfield-import",
-    importedAt: input.importedAt || timestamp,
+    kind: "brownfield-extract",
+    extractedAt: input.importedAt || timestamp,
     ...(input.refreshedAt ? { refreshedAt: input.refreshedAt } : {}),
     source: {
       path: path.resolve(input.sourceRoot),
       hashAlgorithm: "sha256",
       ignoredRoots: (input.ignoredRoots || []).map((item) => path.resolve(item))
     },
-    import: {
+    extract: {
       tracks: input.tracks || [],
       findingsCount: input.findingsCount || 0,
-      candidateCounts: input.candidateCounts || {}
+      candidateCounts: input.candidateCounts || {},
+      extractorPackages: input.extractorPackages || []
     },
     ownership: {
-      importedArtifacts: "project-owned",
-      note: "Topogram artifacts created by import are editable after import. Source hashes record the brownfield app evidence trusted at import time."
+      extractedArtifacts: "project-owned",
+      note: "Topogram artifacts created by extraction are editable after extraction. Source hashes record the brownfield app evidence trusted at extraction time."
     },
     ...(input.refresh ? { refresh: input.refresh } : {}),
     files: input.files || []
@@ -79,11 +80,11 @@ export function buildTopogramImportStatus(projectRoot) {
       source: null,
       content: { changed: [], added: [], removed: [] },
       diagnostics: [{
-        code: "topogram_import_missing",
+        code: "topogram_extract_missing",
         severity: "error",
-        message: `${TOPOGRAM_IMPORT_FILE} was not found. This workspace does not have brownfield import provenance.`,
+        message: `${TOPOGRAM_IMPORT_FILE} was not found. This workspace does not have brownfield extraction provenance.`,
         path: importPath,
-        suggestedFix: "Run `topogram import <app-path> --out <target>` to create an imported Topogram workspace."
+        suggestedFix: "Run `topogram extract <app-path> --out <target>` to create an extracted Topogram workspace."
       }],
       errors: [`${TOPOGRAM_IMPORT_FILE} was not found.`]
     };
@@ -92,7 +93,7 @@ export function buildTopogramImportStatus(projectRoot) {
   const source = JSON.parse(fs.readFileSync(importPath, "utf8"));
   const sourceRoot = path.resolve(source.source?.path || "");
   if (!sourceRoot || !fs.existsSync(sourceRoot) || !fs.statSync(sourceRoot).isDirectory()) {
-    const message = `Imported source path was not found: ${source.source?.path || "unknown"}`;
+    const message = `Extracted source path was not found: ${source.source?.path || "unknown"}`;
     return {
       ok: false,
       exists: true,
@@ -101,11 +102,11 @@ export function buildTopogramImportStatus(projectRoot) {
       source,
       content: { changed: [], added: [], removed: [] },
       diagnostics: [{
-        code: "topogram_import_source_missing",
+      code: "topogram_extract_source_missing",
         severity: "error",
         message,
         path: source.source?.path || null,
-        suggestedFix: "Restore the imported source path or rerun import from the current brownfield app location."
+        suggestedFix: "Restore the extracted source path or rerun extract from the current brownfield app location."
       }],
       errors: [message]
     };
@@ -147,12 +148,12 @@ export function buildTopogramImportStatus(projectRoot) {
     source,
     content,
     diagnostics: clean ? [] : [{
-      code: "topogram_import_source_changed",
+      code: "topogram_extract_source_changed",
       severity: "error",
-      message: "Imported source files changed since they were trusted for this import.",
+      message: "Extracted source files changed since they were trusted for this extraction.",
       path: sourceRoot,
-      suggestedFix: "Review the source changes. If they should drive Topogram changes, rerun import or update the Topogram artifacts manually."
+      suggestedFix: "Review the source changes. If they should drive Topogram changes, rerun extract or update the Topogram artifacts manually."
     }],
-    errors: clean ? [] : ["Imported source files changed since import."]
+    errors: clean ? [] : ["Extracted source files changed since extraction."]
   };
 }

package/src/init-project.js

@@ -0,0 +1,215 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { defaultSdlcPolicy, SDLC_POLICY_FILE } from "./sdlc/policy.js";
+import { DEFAULT_TOPO_FOLDER_NAME, DEFAULT_WORKSPACE_PATH, PROJECT_CONFIG_FILE } from "./workspace-paths.js";
+
+/**
+ * @typedef {Object} InitProjectOptions
+ * @property {string} [targetPath]
+ * @property {boolean} [withSdlc]
+ */
+
+/**
+ * @typedef {Object} InitProjectResult
+ * @property {boolean} ok
+ * @property {string} projectRoot
+ * @property {string} workspaceRoot
+ * @property {string} projectConfigPath
+ * @property {string[]} created
+ * @property {string[]} skipped
+ * @property {Record<string, any>} projectConfig
+ * @property {{ enabled: boolean, path: string|null }} sdlc
+ */
+
+/**
+ * @param {string} projectRoot
+ * @param {string} targetPath
+ * @returns {string}
+ */
+function relativeProjectPath(projectRoot, targetPath) {
+  const relative = path.relative(projectRoot, targetPath);
+  return relative ? relative.split(path.sep).join("/") : ".";
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} filePath
+ * @param {string} content
+ * @param {string[]} created
+ * @param {string[]} skipped
+ * @returns {void}
+ */
+function writeIfMissing(projectRoot, filePath, content, created, skipped) {
+  if (fs.existsSync(filePath)) {
+    skipped.push(relativeProjectPath(projectRoot, filePath));
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf8");
+  created.push(relativeProjectPath(projectRoot, filePath));
+}
+
+/**
+ * @returns {Record<string, any>}
+ */
+function defaultMaintainedProjectConfig() {
+  return {
+    version: "0.1",
+    workspace: DEFAULT_WORKSPACE_PATH,
+    outputs: {
+      app: {
+        path: ".",
+        ownership: "maintained"
+      }
+    },
+    topology: {
+      runtimes: []
+    }
+  };
+}
+
+/**
+ * @returns {string}
+ */
+function initializedReadme() {
+  return `# Topogram Project
+
+Initialized with \`topogram init\`.
+
+This repository is treated as a maintained app or workspace: Topogram will not
+overwrite source code under \`./\`. Use \`topogram emit\` for contracts, reports,
+snapshots, and proposals, and edit maintained app code directly after reading
+focused query packets.
+
+## First Commands
+
+\`\`\`bash
+topogram agent brief --json
+topogram check --json
+topogram query list --json
+\`\`\`
+
+To adopt enforced SDLC after initialization, run:
+
+\`\`\`bash
+topogram sdlc policy init .
+\`\`\`
+
+## Source
+
+- \`topo/\` is the project-owned Topogram workspace.
+- \`topogram.project.json\` declares workspace, output ownership, and runtime topology.
+- Output \`app\` points at \`.\` with \`maintained\` ownership.
+`;
+}
+
+/**
+ * @returns {string}
+ */
+function initializedAgentsGuide() {
+  return `# Agent Guide
+
+This repository was initialized with \`topogram init\`.
+
+Start with:
+
+\`\`\`bash
+topogram agent brief --json
+topogram check --json
+topogram query list --json
+\`\`\`
+
+Edit \`topo/**\` and \`topogram.project.json\` for Topogram source. The project
+output is maintained, so app/source files under \`./\` are human-owned and may be
+edited directly after reading focused packets.
+
+Use \`topogram emit <target>\` for contracts, reports, snapshots, migration
+plans, and agent context. Do not expect \`topogram generate\` to overwrite this
+maintained app unless output ownership is deliberately changed.
+
+If \`topogram.sdlc-policy.json\` exists, use SDLC commands for task and status
+work before protected edits:
+
+\`\`\`bash
+topogram sdlc policy explain --json
+topogram sdlc prep commit . --json
+\`\`\`
+`;
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {void}
+ */
+function assertInitTarget(projectRoot) {
+  if (fs.existsSync(projectRoot) && !fs.statSync(projectRoot).isDirectory()) {
+    throw new Error(`Cannot initialize Topogram at '${projectRoot}' because it is not a directory.`);
+  }
+  const configPath = path.join(projectRoot, PROJECT_CONFIG_FILE);
+  if (fs.existsSync(configPath)) {
+    throw new Error(`Refusing to initialize Topogram because ${PROJECT_CONFIG_FILE} already exists.`);
+  }
+  const workspaceRoot = path.join(projectRoot, DEFAULT_TOPO_FOLDER_NAME);
+  if (fs.existsSync(workspaceRoot)) {
+    if (!fs.statSync(workspaceRoot).isDirectory()) {
+      throw new Error(`Refusing to initialize Topogram because ${DEFAULT_TOPO_FOLDER_NAME}/ exists and is not a directory.`);
+    }
+    const entries = fs.readdirSync(workspaceRoot).filter(/** @param {string} entry */ (entry) => entry !== ".DS_Store");
+    if (entries.length > 0) {
+      throw new Error(`Refusing to initialize Topogram because ${DEFAULT_TOPO_FOLDER_NAME}/ already exists and is not empty.`);
+    }
+  }
+}
+
+/**
+ * @param {InitProjectOptions} [options]
+ * @returns {InitProjectResult}
+ */
+export function initTopogramProject(options = {}) {
+  const projectRoot = path.resolve(options.targetPath || ".");
+  assertInitTarget(projectRoot);
+  fs.mkdirSync(projectRoot, { recursive: true });
+
+  /** @type {string[]} */
+  const created = [];
+  /** @type {string[]} */
+  const skipped = [];
+  const workspaceRoot = path.join(projectRoot, DEFAULT_TOPO_FOLDER_NAME);
+  fs.mkdirSync(workspaceRoot, { recursive: true });
+  created.push(DEFAULT_TOPO_FOLDER_NAME);
+
+  writeIfMissing(projectRoot, path.join(workspaceRoot, ".gitkeep"), "", created, skipped);
+  const projectConfig = defaultMaintainedProjectConfig();
+  const projectConfigPath = path.join(projectRoot, PROJECT_CONFIG_FILE);
+  fs.writeFileSync(projectConfigPath, `${JSON.stringify(projectConfig, null, 2)}\n`, "utf8");
+  created.push(PROJECT_CONFIG_FILE);
+  writeIfMissing(projectRoot, path.join(projectRoot, "README.md"), initializedReadme(), created, skipped);
+  writeIfMissing(projectRoot, path.join(projectRoot, "AGENTS.md"), initializedAgentsGuide(), created, skipped);
+  const sdlcPolicyPath = path.join(projectRoot, SDLC_POLICY_FILE);
+  if (options.withSdlc) {
+    writeIfMissing(
+      projectRoot,
+      sdlcPolicyPath,
+      `${JSON.stringify(defaultSdlcPolicy(), null, 2)}\n`,
+      created,
+      skipped
+    );
+  }
+
+  return {
+    ok: true,
+    projectRoot,
+    workspaceRoot,
+    projectConfigPath,
+    created,
+    skipped,
+    projectConfig,
+    sdlc: {
+      enabled: options.withSdlc ? fs.existsSync(sdlcPolicyPath) : false,
+      path: options.withSdlc ? sdlcPolicyPath : null
+    }
+  };
+}

package/src/new-project/constants.js

@@ -31,7 +31,7 @@ export const SURFACE_ORDER = new Map([
  * @returns {string}
  */
 export function unsupportedTemplateSymlinkMessage(templateId, relativePath) {
-  return `Template '${templateId}' contains unsupported symlink '${relativePath}'. Template packs must copy real files because Topogram records hashes for copied workspace and implementation/ content; symlinks can point outside the trusted template root. Replace the symlink with a real file or directory before running topogram new or topogram template check.`;
+  return `Template '${templateId}' contains unsupported symlink '${relativePath}'. Template packs must copy real files because Topogram records hashes for copied workspace and implementation/ content; symlinks can point outside the trusted template root. Replace the symlink with a real file or directory before running topogram copy or topogram template check.`;
 }
 
 /**

package/src/new-project/create.js

@@ -36,7 +36,7 @@ export function createNewProject({
   templateProvenance = null
 }) {
   if (!targetPath) {
-    throw new Error("topogram new requires <path>.");
+    throw new Error("topogram copy requires <target>.");
   }
   const projectRoot = path.resolve(targetPath);
   assertProjectOutsideEngine(projectRoot, engineRoot);
@@ -68,7 +68,7 @@ export function createNewProject({
     writeTemplateTrustRecord(projectRoot, projectConfig);
     warnings.push(
       `Template '${template.manifest.id}' copied implementation/ code into this project. ` +
-        "topogram new did not execute it, but topogram generate may load it later. " +
+        "topogram copy did not execute it, but topogram generate may load it later. " +
         "Recorded local trust in .topogram-template-trust.json."
     );
   }

package/src/new-project/project-files.js

@@ -247,7 +247,7 @@ export function writeProjectReadme(projectRoot, projectConfig) {
   provenanceLines.push(`- Executable implementation: \`${template.includesExecutableImplementation ? "yes" : "no"}\``);
   const readme = `# ${packageNameFromPath(projectRoot)}
 
-Generated by \`topogram new\`.
+Copied by \`topogram copy\`.
 
 ## Template
 
@@ -263,7 +263,7 @@ Edit the workspace folder \`${DEFAULT_TOPO_FOLDER_NAME}/\` and \`topogram.projec
 Generated app code is written to \`app/\`.
 Use \`topogram emit <target>\` to inspect contracts, reports, snapshots, and other artifacts without regenerating the app.
 Agents should start with \`AGENTS.md\` and \`npm run agent:brief\`. The direct \`topogram agent brief --json\` command is the canonical machine-readable first-run guidance.
-${template.includesExecutableImplementation ? "\nThis template copied `implementation/` code. `topogram new` did not execute it; review `implementation/`, `topogram.template-policy.json`, and `.topogram-template-trust.json` before regenerating after edits.\n" : ""}
+${template.includesExecutableImplementation ? "\nThis template copied `implementation/` code. `topogram copy` did not execute it; review `implementation/`, `topogram.template-policy.json`, and `.topogram-template-trust.json` before regenerating after edits.\n" : ""}
 `;
   fs.writeFileSync(path.join(projectRoot, "README.md"), readme, "utf8");
 }
@@ -339,12 +339,12 @@ npm run query:show -- widget-behavior
 
 - Local edits to template-derived Topogram files are project-owned.
 - Use \`npm run source:status\` and \`npm run template:update:recommend\` before applying template updates.
-${hasImplementation ? "- This project has executable `implementation/` code. `topogram new` did not execute it. Do not refresh trust until the implementation has been reviewed.\n" : "- This template does not declare executable implementation code.\n"}
-## Import And Adoption
+${hasImplementation ? "- This project has executable `implementation/` code. `topogram copy` did not execute it. Do not refresh trust until the implementation has been reviewed.\n" : "- This template does not declare executable implementation code.\n"}
+## Extract And Adopt
 
-- If \`.topogram-import.json\` exists, agents should run \`topogram import check . --json\`, \`topogram import plan . --json\`, \`topogram import adopt --list . --json\`, \`topogram import status . --json\`, and \`topogram import history . --verify --json\`.
-- Import JSON payloads expose \`workspaceRoot\`; prefer it as the canonical project-owned workspace path.
-- Imported Topogram files are project-owned after adoption; source hashes record trusted import evidence at the time of import.
+- If \`.topogram-extract.json\` exists, agents should run \`topogram extract check . --json\`, \`topogram extract plan . --json\`, \`topogram adopt --list . --json\`, \`topogram extract status . --json\`, and \`topogram extract history . --verify --json\`.
+- Extract JSON payloads expose \`workspaceRoot\`; prefer it as the canonical project-owned workspace path.
+- Extracted Topogram files are project-owned after adoption; source hashes record trusted source evidence at the time of extraction.
 
 ## Verification Gates
 

package/src/package-adapters/adapter.js

@@ -0,0 +1,64 @@
+// @ts-check
+
+import path from "node:path";
+import { createRequire } from "node:module";
+
+/**
+ * @param {any} moduleValue
+ * @param {string|null|undefined} exportName
+ * @returns {any}
+ */
+export function selectPackageExport(moduleValue, exportName) {
+  if (exportName) {
+    return moduleValue?.[exportName] || moduleValue?.default?.[exportName] || null;
+  }
+  return moduleValue?.default || moduleValue;
+}
+
+/**
+ * @param {{
+ *   packageRoot: string,
+ *   exportName?: string|null,
+ *   packageLabel: string
+ * }} options
+ * @returns {{ adapter: any|null, error: string|null }}
+ */
+export function loadLocalPackageAdapter(options) {
+  try {
+    const packageJsonPath = path.join(options.packageRoot, "package.json");
+    const requireFromPackage = createRequire(packageJsonPath);
+    return {
+      adapter: selectPackageExport(requireFromPackage(options.packageRoot), options.exportName),
+      error: null
+    };
+  } catch (error) {
+    return {
+      adapter: null,
+      error: `${options.packageLabel} export could not be loaded from '${options.packageRoot}': ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+
+/**
+ * @param {{
+ *   packageName: string,
+ *   rootDir: string,
+ *   exportName?: string|null,
+ *   packageLabel: string
+ * }} options
+ * @returns {{ adapter: any|null, error: string|null }}
+ */
+export function loadInstalledPackageAdapter(options) {
+  try {
+    const requireFromRoot = createRequire(path.join(options.rootDir, "package.json"));
+    return {
+      adapter: selectPackageExport(requireFromRoot(options.packageName), options.exportName),
+      error: null
+    };
+  } catch (error) {
+    return {
+      adapter: null,
+      error: `${options.packageLabel} '${options.packageName}' export could not be loaded from '${options.rootDir}': ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}

package/src/package-adapters/file-map.js

@@ -0,0 +1,30 @@
+// @ts-check
+
+import path from "node:path";
+
+/**
+ * @param {any} files
+ * @param {{ filePathMessage: string, contentMessage: (filePath: string) => string }} messages
+ * @returns {{ ok: boolean, message: string }}
+ */
+export function validateRelativeStringFileMap(files, messages) {
+  if (!files || typeof files !== "object" || Array.isArray(files)) {
+    return { ok: false, message: "files must be an object" };
+  }
+  for (const [filePath, content] of Object.entries(files)) {
+    const normalizedPath = typeof filePath === "string" ? path.normalize(filePath) : "";
+    if (
+      typeof filePath !== "string" ||
+      filePath.length === 0 ||
+      path.isAbsolute(filePath) ||
+      normalizedPath === ".." ||
+      normalizedPath.startsWith(`..${path.sep}`)
+    ) {
+      return { ok: false, message: messages.filePathMessage };
+    }
+    if (typeof content !== "string") {
+      return { ok: false, message: messages.contentMessage(filePath) };
+    }
+  }
+  return { ok: true, message: "files are valid" };
+}

package/src/package-adapters/index.js

@@ -0,0 +1,27 @@
+// @ts-check
+
+export {
+  loadInstalledPackageAdapter,
+  loadLocalPackageAdapter,
+  selectPackageExport
+} from "./adapter.js";
+export {
+  loadPackageManifest,
+  resolvePackageManifestPath
+} from "./manifest.js";
+export {
+  isPathSpec,
+  packageInstallCommand,
+  packageInstallHint,
+  packageNameFromSpec,
+  packageResolutionBase
+} from "./spec.js";
+export {
+  optionalStringArray,
+  optionalStringRecord,
+  packageAllowedByPolicy,
+  packageScopeFromName
+} from "./policy.js";
+export {
+  validateRelativeStringFileMap
+} from "./file-map.js";

package/src/package-adapters/manifest.js

@@ -0,0 +1,108 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+import { packageInstallHint, packageResolutionBase } from "./spec.js";
+
+/**
+ * @typedef {Object} PackageManifestResolution
+ * @property {string|null} manifestPath
+ * @property {string|null} packageRoot
+ * @property {string|null} error
+ */
+
+/**
+ * @typedef {{ ok: boolean, errors: string[] }} ManifestValidation
+ */
+
+/**
+ * @param {string} packageName
+ * @param {string} manifestFile
+ * @param {string|null|undefined} rootDir
+ * @param {string} packageLabel
+ * @returns {PackageManifestResolution}
+ */
+export function resolvePackageManifestPath(packageName, manifestFile, rootDir = process.cwd(), packageLabel = "Package") {
+  const requireFromRoot = createRequire(packageResolutionBase(rootDir));
+  try {
+    const manifestPath = requireFromRoot.resolve(`${packageName}/${manifestFile}`);
+    return {
+      manifestPath,
+      packageRoot: path.dirname(manifestPath),
+      error: null
+    };
+  } catch (manifestError) {
+    try {
+      const packageJsonPath = requireFromRoot.resolve(`${packageName}/package.json`);
+      const packageRoot = path.dirname(packageJsonPath);
+      const manifestPath = path.join(packageRoot, manifestFile);
+      if (!fs.existsSync(manifestPath)) {
+        return {
+          manifestPath: null,
+          packageRoot,
+          error: `${packageLabel} '${packageName}' is missing ${manifestFile}`
+        };
+      }
+      return {
+        manifestPath,
+        packageRoot,
+        error: null
+      };
+    } catch {
+      const detail = manifestError instanceof Error ? manifestError.message : String(manifestError);
+      const installHint = packageInstallHint(packageName);
+      return {
+        manifestPath: null,
+        packageRoot: null,
+        error: `${packageLabel} '${packageName}' could not be resolved from '${rootDir || process.cwd()}': ${detail}${installHint ? `. ${installHint}` : ""}`
+      };
+    }
+  }
+}
+
+/**
+ * @template T
+ * @param {{
+ *   packageName: string,
+ *   rootDir?: string|null,
+ *   manifestFile: string,
+ *   packageLabel: string,
+ *   validateManifest: (manifest: any) => ManifestValidation
+ * }} options
+ * @returns {{ manifest: T|null, errors: string[], manifestPath: string|null, packageRoot: string|null }}
+ */
+export function loadPackageManifest(options) {
+  const resolved = resolvePackageManifestPath(
+    options.packageName,
+    options.manifestFile,
+    options.rootDir || process.cwd(),
+    options.packageLabel
+  );
+  if (!resolved.manifestPath) {
+    return {
+      manifest: null,
+      errors: [resolved.error || `${options.packageLabel} '${options.packageName}' could not be resolved`],
+      manifestPath: null,
+      packageRoot: resolved.packageRoot
+    };
+  }
+  try {
+    const manifest = JSON.parse(fs.readFileSync(resolved.manifestPath, "utf8"));
+    const validation = options.validateManifest(manifest);
+    return {
+      manifest: validation.ok ? /** @type {T} */ (manifest) : null,
+      errors: validation.errors,
+      manifestPath: resolved.manifestPath,
+      packageRoot: resolved.packageRoot
+    };
+  } catch (error) {
+    return {
+      manifest: null,
+      errors: [`${options.packageLabel} '${options.packageName}' manifest could not be read: ${error instanceof Error ? error.message : String(error)}`],
+      manifestPath: resolved.manifestPath,
+      packageRoot: resolved.packageRoot
+    };
+  }
+}

package/src/package-adapters/policy.js

@@ -0,0 +1,81 @@
+// @ts-check
+
+/**
+ * @typedef {Object} PackagePolicy
+ * @property {string} version
+ * @property {string[]} allowedPackageScopes
+ * @property {string[]} allowedPackages
+ * @property {Record<string, string>} pinnedVersions
+ */
+
+/**
+ * @param {unknown} value
+ * @param {string} fieldName
+ * @param {string} policyPath
+ * @returns {string[]}
+ */
+export function optionalStringArray(value, fieldName, policyPath) {
+  if (value == null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${policyPath} ${fieldName} must be an array of strings.`);
+  }
+  return value.map((item) => {
+    if (typeof item !== "string" || item.length === 0) {
+      throw new Error(`${policyPath} ${fieldName} must contain only non-empty strings.`);
+    }
+    return item;
+  });
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} policyPath
+ * @param {string} [pinnedLabel]
+ * @returns {Record<string, string>}
+ */
+export function optionalStringRecord(value, policyPath, pinnedLabel = "package ids") {
+  if (value == null) {
+    return {};
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${policyPath} pinnedVersions must be an object of ${pinnedLabel} to versions.`);
+  }
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+    if (typeof item !== "string" || item.length === 0) {
+      throw new Error(`${policyPath} pinnedVersions['${key}'] must be a non-empty string.`);
+    }
+    return [key, item];
+  }));
+}
+
+/**
+ * @param {string} packageName
+ * @returns {string|null}
+ */
+export function packageScopeFromName(packageName) {
+  return packageName.startsWith("@") ? packageName.split("/")[0] || null : null;
+}
+
+/**
+ * @param {string} allowed
+ * @param {string|null} scope
+ * @returns {boolean}
+ */
+function packageScopeMatches(allowed, scope) {
+  return Boolean(scope && (allowed === scope || allowed === `${scope}/*`));
+}
+
+/**
+ * @param {PackagePolicy} policy
+ * @param {string} packageName
+ * @returns {boolean}
+ */
+export function packageAllowedByPolicy(policy, packageName) {
+  if (policy.allowedPackages.includes(packageName)) {
+    return true;
+  }
+  const scope = packageScopeFromName(packageName);
+  return policy.allowedPackageScopes.some((allowed) => packageScopeMatches(allowed, scope));
+}