@shrkcrft/packs 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/packs
+
+SharkCraft pack discovery + loading: scan node_modules for sharkcraft manifests and surface contributions.
+
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/packs
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/discovery/discover-packs.d.ts

@@ -0,0 +1,28 @@
+import type { IPackDiscoveryResult } from '../model/pack-discovery.js';
+export interface DiscoverPacksOptions {
+    /** Project root to look up node_modules in. Must be absolute. */
+    projectRoot: string;
+    /**
+     * Optional secondary roots to also scan (e.g. for tests that drop a pack
+     * outside node_modules). Each must contain a `node_modules` directory.
+     */
+    extraRoots?: readonly string[];
+    /** When true, surfaces detailed warnings even for "no manifest" packages. */
+    verbose?: boolean;
+    /**
+     * If true, every signed pack is verified against the SHARKCRAFT_PACK_SECRET
+     * env var (or {@link DiscoverPacksOptions.packSecret}). Unsigned packs are
+     * not penalized — verification is opt-in.
+     */
+    verifySignatures?: boolean;
+    /** Override the secret used for signature verification. */
+    packSecret?: string;
+}
+/**
+ * Walk `<projectRoot>/node_modules/` (+ any extra roots) and surface every
+ * package whose `package.json` declares a `sharkcraft` field. For each, load
+ * the manifest and run validatePackManifest. Returns a structured discovery
+ * result; never throws on individual pack failures.
+ */
+export declare function discoverPacks(options: DiscoverPacksOptions): Promise<IPackDiscoveryResult>;
+//# sourceMappingURL=discover-packs.d.ts.map

package/dist/discovery/discover-packs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover-packs.d.ts","sourceRoot":"","sources":["../../src/discovery/discover-packs.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAmB,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAqHxF,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAoIhG"}

package/dist/discovery/discover-packs.js

@@ -0,0 +1,251 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { PACK_SECRET_ENV, validatePackManifest, verifyPackManifest, } from '@shrkcrft/plugin-api';
+function readPackageJson(pkgPath) {
+    try {
+        return JSON.parse(readFileSync(pkgPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function resolveManifestPath(packageRoot, manifestField) {
+    if (typeof manifestField === 'string') {
+        return nodePath.resolve(packageRoot, manifestField);
+    }
+    if (manifestField && typeof manifestField === 'object') {
+        const m = manifestField.manifest;
+        if (typeof m === 'string')
+            return nodePath.resolve(packageRoot, m);
+    }
+    return null;
+}
+function emptyCounts() {
+    return {
+        knowledgeFiles: 0,
+        ruleFiles: 0,
+        pathFiles: 0,
+        templateFiles: 0,
+        pipelineFiles: 0,
+        docsFiles: 0,
+        presetFiles: 0,
+        scaffoldPatternFiles: 0,
+        policyCheckFiles: 0,
+        constructFiles: 0,
+        constructFacetFiles: 0,
+        playbookFiles: 0,
+    };
+}
+function countContributions(c) {
+    const out = emptyCounts();
+    if (!c)
+        return out;
+    out.knowledgeFiles = c.knowledgeFiles?.length ?? 0;
+    out.ruleFiles = c.ruleFiles?.length ?? 0;
+    out.pathFiles = c.pathFiles?.length ?? 0;
+    out.templateFiles = c.templateFiles?.length ?? 0;
+    out.pipelineFiles = c.pipelineFiles?.length ?? 0;
+    out.docsFiles = c.docsFiles?.length ?? 0;
+    out.presetFiles = c.presetFiles?.length ?? 0;
+    out.scaffoldPatternFiles = c.scaffoldPatternFiles?.length ?? 0;
+    out.policyCheckFiles = c.policyCheckFiles?.length ?? 0;
+    out.constructFiles = c.constructFiles?.length ?? 0;
+    out.constructFacetFiles = c.constructFacetFiles?.length ?? 0;
+    out.playbookFiles = c.playbookFiles?.length ?? 0;
+    return out;
+}
+/**
+ * Yield every package.json under node_modules (top-level + first-level
+ * @scope/* entries). Skips the .bin / .cache / .pnpm-style internals and
+ * common nested node_modules to avoid recursion blow-up.
+ */
+function* scanNodeModules(nodeModulesPath) {
+    let entries;
+    try {
+        entries = readdirSync(nodeModulesPath, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const name = String(entry.name);
+        if (name.startsWith('.'))
+            continue;
+        if (name === 'node_modules')
+            continue;
+        const dir = nodePath.join(nodeModulesPath, name);
+        let isDir = false;
+        try {
+            isDir = entry.isDirectory() || entry.isSymbolicLink();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir)
+            continue;
+        if (name.startsWith('@')) {
+            // Scoped package directory: recurse one level.
+            let scoped;
+            try {
+                scoped = readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const scopedEntry of scoped) {
+                const scopedName = String(scopedEntry.name);
+                if (scopedName.startsWith('.'))
+                    continue;
+                const packageRoot = nodePath.join(dir, scopedName);
+                const packageJsonPath = nodePath.join(packageRoot, 'package.json');
+                if (existsSync(packageJsonPath)) {
+                    yield { packageRoot, packageJsonPath };
+                }
+            }
+        }
+        else {
+            const packageJsonPath = nodePath.join(dir, 'package.json');
+            if (existsSync(packageJsonPath)) {
+                yield { packageRoot: dir, packageJsonPath };
+            }
+        }
+    }
+}
+/**
+ * Walk `<projectRoot>/node_modules/` (+ any extra roots) and surface every
+ * package whose `package.json` declares a `sharkcraft` field. For each, load
+ * the manifest and run validatePackManifest. Returns a structured discovery
+ * result; never throws on individual pack failures.
+ */
+export async function discoverPacks(options) {
+    const projectRoot = nodePath.resolve(options.projectRoot);
+    const nodeModulesPath = nodePath.join(projectRoot, 'node_modules');
+    const nodeModulesExists = existsSync(nodeModulesPath);
+    const result = {
+        projectRoot,
+        nodeModulesPath,
+        nodeModulesExists,
+        scannedPackageCount: 0,
+        discoveredPacks: [],
+        validPacks: [],
+        invalidPacks: [],
+        warnings: [],
+    };
+    const roots = [
+        ...(nodeModulesExists ? [nodeModulesPath] : []),
+        ...(options.extraRoots ?? []).map((r) => nodePath.resolve(r)),
+    ];
+    if (roots.length === 0) {
+        result.warnings.push(`No node_modules at ${nodeModulesPath} and no extra roots provided.`);
+        return result;
+    }
+    const seenPackagePaths = new Set();
+    for (const root of roots) {
+        for (const { packageRoot, packageJsonPath } of scanNodeModules(root)) {
+            // Dedup by realpath so workspace symlinks aren't visited twice.
+            let canonical = packageRoot;
+            try {
+                canonical = realpathSync(packageRoot);
+            }
+            catch {
+                // ignore — use the original path
+            }
+            if (seenPackagePaths.has(canonical))
+                continue;
+            seenPackagePaths.add(canonical);
+            result.scannedPackageCount += 1;
+            const pkg = readPackageJson(packageJsonPath);
+            if (!pkg)
+                continue;
+            if (pkg.sharkcraft === undefined)
+                continue;
+            const manifestPath = resolveManifestPath(packageRoot, pkg.sharkcraft);
+            const packageName = pkg.name ?? '<unnamed>';
+            const packageVersion = pkg.version ?? '0.0.0';
+            const discovered = {
+                packageName,
+                packageVersion,
+                manifestPath: manifestPath ?? '',
+                packageRoot,
+                contributionCounts: emptyCounts(),
+                validationIssues: [],
+                valid: false,
+            };
+            if (!manifestPath) {
+                discovered.loadError = 'manifest path could not be resolved from package.json';
+                result.discoveredPacks.push(discovered);
+                result.invalidPacks.push(discovered);
+                continue;
+            }
+            if (!existsSync(manifestPath)) {
+                discovered.loadError = `manifest file does not exist: ${manifestPath}`;
+                result.discoveredPacks.push(discovered);
+                result.invalidPacks.push(discovered);
+                continue;
+            }
+            try {
+                let manifest;
+                if (manifestPath.endsWith('.json')) {
+                    // Signed JSON manifest path. Never dynamic-import — JSON is data, not
+                    // code, and treating it as code defeats the point of signing.
+                    const raw = readFileSync(manifestPath, 'utf8');
+                    manifest = JSON.parse(raw);
+                }
+                else {
+                    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(manifestPath).href)));
+                    manifest = (mod.default ?? mod);
+                }
+                if (!manifest) {
+                    discovered.loadError = 'manifest module has no default export';
+                }
+                else {
+                    discovered.manifest = manifest;
+                    discovered.contributionCounts = countContributions(manifest.contributions);
+                    const v = validatePackManifest(manifest);
+                    discovered.validationIssues = v.issues;
+                    discovered.valid = v.valid;
+                    if (options.verifySignatures) {
+                        const verifyResult = verifyPackManifest(manifest, { secret: options.packSecret });
+                        discovered.signatureStatus = verifyResult.ok ? 'verified' : verifyResult.status;
+                        discovered.signatureMessage = verifyResult.ok
+                            ? 'Signature verified.'
+                            : verifyResult.message;
+                        if (!verifyResult.ok && verifyResult.status === 'invalid-signature') {
+                            // Tampered manifest — strip validity.
+                            discovered.valid = false;
+                            discovered.validationIssues.push({
+                                field: 'signature',
+                                message: 'Signature does not match — pack may have been tampered with.',
+                            });
+                        }
+                    }
+                    else if (manifest.signature) {
+                        discovered.signatureStatus = 'not-checked';
+                        discovered.signatureMessage = `Signed but not verified. Set ${PACK_SECRET_ENV} and run packs verify.`;
+                    }
+                }
+            }
+            catch (e) {
+                discovered.loadError = `failed to import manifest: ${e.message}`;
+            }
+            result.discoveredPacks.push(discovered);
+            if (discovered.valid)
+                result.validPacks.push(discovered);
+            else
+                result.invalidPacks.push(discovered);
+            if (!discovered.valid && options.verbose) {
+                result.warnings.push(`pack ${packageName}@${packageVersion} invalid: ${discovered.loadError ?? discovered.validationIssues.map((i) => i.field).join(', ')}`);
+            }
+        }
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './model/pack-discovery.js';
+export * from './discovery/discover-packs.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./model/pack-discovery.js";
+export * from "./discovery/discover-packs.js";

package/dist/model/pack-discovery.d.ts

@@ -0,0 +1,73 @@
+import type { ISharkCraftPackManifest } from '@shrkcrft/plugin-api';
+export interface IDiscoveredPack {
+    /** Published package name (from package.json). */
+    packageName: string;
+    packageVersion: string;
+    /** Resolved absolute path to the loaded manifest file. */
+    manifestPath: string;
+    /** Absolute path to the package's root. */
+    packageRoot: string;
+    /** Parsed manifest, if it loaded. */
+    manifest?: ISharkCraftPackManifest;
+    /** Number of contribution **files** of each kind. Zero if not declared. */
+    contributionCounts: {
+        knowledgeFiles: number;
+        ruleFiles: number;
+        pathFiles: number;
+        templateFiles: number;
+        pipelineFiles: number;
+        docsFiles: number;
+        presetFiles: number;
+        scaffoldPatternFiles: number;
+        policyCheckFiles: number;
+        constructFiles: number;
+        constructFacetFiles: number;
+        playbookFiles: number;
+    };
+    /**
+     * Number of **resolved objects** loaded from this pack's contributions, after
+     * de-duplication against local entries and inside the pack. Populated by the
+     * inspector after pack discovery completes. Zero when discovery ran in
+     * isolation (no contribution loading).
+     */
+    resolvedCounts?: {
+        knowledgeEntries: number;
+        rules: number;
+        pathConventions: number;
+        templates: number;
+        pipelines: number;
+        docs: number;
+        presets: number;
+        scaffoldPatterns: number;
+        policyChecks: number;
+    };
+    /** Validation issues from validatePackManifest. */
+    validationIssues: Array<{
+        field: string;
+        message: string;
+    }>;
+    /** Manifest-level load error message, if any. */
+    loadError?: string;
+    /** True if the manifest loaded and validated cleanly. */
+    valid: boolean;
+    /** Signature verification status, when applicable. */
+    signatureStatus?: 'verified' | 'invalid-signature' | 'missing-signature' | 'missing-secret' | 'not-checked';
+    /** Free-form message accompanying the signature status. */
+    signatureMessage?: string;
+}
+export interface IPackDiscoveryResult {
+    projectRoot: string;
+    /** node_modules directory scanned. May be missing. */
+    nodeModulesPath: string;
+    nodeModulesExists: boolean;
+    /** Total number of package.json files we inspected. */
+    scannedPackageCount: number;
+    /** Packs that have a manifest field (valid or not). */
+    discoveredPacks: IDiscoveredPack[];
+    /** Convenience subsets. */
+    validPacks: IDiscoveredPack[];
+    invalidPacks: IDiscoveredPack[];
+    /** Free-form warnings during discovery. */
+    warnings: string[];
+}
+//# sourceMappingURL=pack-discovery.d.ts.map

package/dist/model/pack-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-discovery.d.ts","sourceRoot":"","sources":["../../src/model/pack-discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,2EAA2E;IAC3E,kBAAkB,EAAE;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,gBAAgB,EAAE,MAAM,CAAC;QACzB,cAAc,EAAE,MAAM,CAAC;QACvB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF;;;;;OAKG;IACH,cAAc,CAAC,EAAE;QACf,gBAAgB,EAAE,MAAM,CAAC;QACzB,KAAK,EAAE,MAAM,CAAC;QACd,eAAe,EAAE,MAAM,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,EAAE,MAAM,CAAC;QACzB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,mDAAmD;IACnD,gBAAgB,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,sDAAsD;IACtD,eAAe,CAAC,EACZ,UAAU,GACV,mBAAmB,GACnB,mBAAmB,GACnB,gBAAgB,GAChB,aAAa,CAAC;IAClB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,uDAAuD;IACvD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,eAAe,EAAE,eAAe,EAAE,CAAC;IACnC,2BAA2B;IAC3B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB"}

package/dist/model/pack-discovery.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@shrkcrft/packs",
+  "version": "0.1.0-alpha.2",
+  "description": "SharkCraft pack discovery + loading: scan node_modules for sharkcraft manifests and surface contributions.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shrkcrft/sharkcraft.git",
+    "directory": "packages/packs"
+  },
+  "homepage": "https://github.com/shrkcrft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/shrkcrft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "packs",
+    "discovery"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.2",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}