@multileaf/ai-workflow 0.1.0 → 0.1.2

package/dist/ownership.js

@@ -0,0 +1,83 @@
+import { parseDocument, stringify } from "yaml";
+import { isAbsolute } from "node:path";
+import { checksumPackage } from "./package-integrity.js";
+import { RESOURCE_TYPES } from "./package-contract.js";
+import { TARGETS } from "./types.js";
+export function createOwnedFile(path, content, metadata = {}) {
+    validateOwnedPath(path);
+    return { path, checksum: `sha256-${checksumPackage(content)}`, ...metadata };
+}
+export function serializeOwnership(files) {
+    const ordered = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const unique = new Set();
+    for (const file of ordered) {
+        validateOwnedPath(file.path);
+        if (unique.has(file.path))
+            throw new Error(`Ownership inventory contains a duplicate path: ${file.path}`);
+        unique.add(file.path);
+        if (!/^sha256-[a-f0-9]{64}$/.test(file.checksum))
+            throw new Error(`Ownership inventory checksum is invalid: ${file.path}`);
+    }
+    return stringify({ schema: 1, files: ordered }, { lineWidth: 0 });
+}
+export function parseOwnership(content) {
+    const document = parseDocument(content, { uniqueKeys: true, strict: true });
+    if (document.errors.length)
+        throw new Error(`Ownership inventory YAML is invalid: ${document.errors[0].message}`);
+    const value = document.toJS();
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Ownership inventory must be a mapping.");
+    const inventory = value;
+    if (Object.keys(inventory).some((key) => !["schema", "files"].includes(key)))
+        throw new Error("Ownership inventory contains an unsupported field.");
+    if (inventory.schema !== 1 || !Array.isArray(inventory.files))
+        throw new Error("Ownership inventory schema or files section is invalid.");
+    const files = inventory.files.map((entry, index) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            throw new Error(`Ownership inventory entry ${index} is invalid.`);
+        const file = entry;
+        if (Object.keys(file).some((key) => !["path", "checksum", "kind", "target", "resourceType", "resourceId"].includes(key)))
+            throw new Error(`Ownership inventory entry ${index} contains an unsupported field.`);
+        if (typeof file.path !== "string" || typeof file.checksum !== "string")
+            throw new Error(`Ownership inventory entry ${index} is missing its path or checksum.`);
+        validateOwnedPath(file.path);
+        if (!/^sha256-[a-f0-9]{64}$/.test(file.checksum))
+            throw new Error(`Ownership inventory checksum is invalid: ${file.path}`);
+        if (file.kind !== undefined &&
+            !["neutral-resource", "target-resource", "ai-init", "supporting-file"].includes(String(file.kind)))
+            throw new Error(`Ownership inventory kind is invalid: ${file.path}`);
+        if (file.target !== undefined && !TARGETS.includes(file.target))
+            throw new Error(`Ownership inventory target is invalid: ${file.path}`);
+        if (file.resourceType !== undefined &&
+            !RESOURCE_TYPES.includes(String(file.resourceType)))
+            throw new Error(`Ownership inventory resource type is invalid: ${file.path}`);
+        if (file.resourceId !== undefined &&
+            (typeof file.resourceId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(file.resourceId)))
+            throw new Error(`Ownership inventory resource id is invalid: ${file.path}`);
+        return {
+            path: file.path,
+            checksum: file.checksum,
+            ...(file.kind !== undefined ? { kind: file.kind } : {}),
+            ...(file.target !== undefined ? { target: file.target } : {}),
+            ...(file.resourceType !== undefined
+                ? { resourceType: file.resourceType }
+                : {}),
+            ...(file.resourceId !== undefined ? { resourceId: file.resourceId } : {}),
+        };
+    });
+    if (new Set(files.map(({ path }) => path)).size !== files.length)
+        throw new Error("Ownership inventory paths must be unique.");
+    return files;
+}
+function validateOwnedPath(path) {
+    if (!path ||
+        isAbsolute(path) ||
+        path.includes("\\") ||
+        path.includes(":") ||
+        [...path].some((character) => {
+            const code = character.codePointAt(0) ?? 0;
+            return code <= 0x1f || code === 0x7f;
+        }) ||
+        path.split("/").some((part) => !part || part === "." || part === ".."))
+        throw new Error("Ownership inventory paths must be normalized project-relative paths.");
+}

package/dist/package-audit.d.ts

@@ -17,3 +17,4 @@ export declare function assertKnownPermissions(permissions: string[]): void;
 export declare function reviewPackagePermissions(pkg: PackageContract, approved: string[]): PermissionReview;
 export declare function serializePermissionReview(pkg: PackageContract): string;
 export declare function assertPackagePermissions(pkg: PackageContract, approved: string[]): void;
+export declare function assertPermissions(permissions: string[], approved: string[]): void;

package/dist/package-audit.js

@@ -22,7 +22,11 @@ export function serializePermissionReview(pkg) {
     return `Package permission review: ${pkg.id}@${pkg.version}\n${permissions.length ? permissions.map((permission) => `- ${permission} (${PACKAGE_PERMISSIONS[permission]})`).join("\n") : "- none"}\nDecision: ${permissions.length ? "explicit approval required" : "no permissions requested"}\n`;
 }
 export function assertPackagePermissions(pkg, approved) {
-    const review = reviewPackagePermissions(pkg, approved);
-    if (!review.allowed)
-        throw new Error(`Package permissions require approval: ${review.unapproved.join(", ")}`);
+    assertPermissions(pkg.permissions, approved);
+}
+export function assertPermissions(permissions, approved) {
+    assertKnownPermissions(permissions);
+    const unapproved = permissions.filter((permission) => !approved.includes(permission));
+    if (unapproved.length)
+        throw new Error(`Package permissions require approval: ${unapproved.join(", ")}`);
 }

package/dist/package-contract.d.ts

@@ -28,3 +28,4 @@ export type PackageContract = {
     targets?: string[];
 };
 export declare function validatePackageContract(content: string, resourceExists?: (path: string) => boolean): PackageContract;
+export declare function validateResourcePath(path: string, field?: string): void;

package/dist/package-contract.js

@@ -1,93 +1,155 @@
+import { parseDocument } from "yaml";
 export const RESOURCE_TYPES = ["skills", "rules", "agents", "hooks", "templates"];
+const TOP_LEVEL_KEYS = new Set([
+    "schema",
+    "id",
+    "version",
+    "description",
+    "language",
+    "provider",
+    "source",
+    "engines",
+    "dependencies",
+    "permissions",
+    "policies",
+    "provenance",
+    "targets",
+    "resources",
+    "provides",
+]);
 export function validatePackageContract(content, resourceExists = () => true) {
-    const required = [
-        "schema",
-        "id",
-        "version",
-        "provider",
-        "source",
-        "resources",
-        "dependencies",
-        "permissions",
-        "provenance",
-    ];
-    for (const field of required) {
-        if (!new RegExp(`^${field}:`, "m").test(content))
-            throw new Error(`Package field '${field}' is required.`);
+    const document = parseDocument(content, { uniqueKeys: true, strict: true });
+    if (document.errors.length)
+        throw new Error(`Package manifest YAML is invalid: ${document.errors[0].message}`);
+    const value = document.toJS();
+    const root = record(value, "manifest");
+    for (const key of Object.keys(root)) {
+        if (!TOP_LEVEL_KEYS.has(key))
+            throw new Error(`Package field '${key}' is not supported.`);
     }
-    const schema = scalar(content, "schema");
-    if (schema !== "1")
-        throw new Error("Package schema must be version 1.");
-    const resources = Object.fromEntries(RESOURCE_TYPES.map((type) => [type, parseResources(content, type)]));
+    const schema = root.schema;
+    if (schema !== 1)
+        throw new Error("Package field 'schema' must be version 1.");
+    const id = requiredString(root, "id");
+    const version = requiredString(root, "version");
+    const provider = requiredString(root, "provider");
+    const source = requiredString(root, "source");
+    optionalString(root, "description", "manifest");
+    optionalString(root, "language", "manifest");
+    const rawResources = record(root.resources, "resources");
+    for (const key of Object.keys(rawResources)) {
+        if (!RESOURCE_TYPES.includes(key))
+            throw new Error(`Package resource section '${key}' is not supported.`);
+    }
+    const resources = {};
     for (const type of RESOURCE_TYPES) {
-        const section = resourceSection(content, type);
-        const entries = section.match(/-\s*\{[^}]*\}/g) ?? [];
-        if (entries.length !== resources[type].length)
-            throw new Error(`Package resource entries in '${type}' require id, version, and path.`);
-        for (const resource of resources[type]) {
+        if (!(type in rawResources))
+            throw new Error(`Package resource section '${type}' is required (use [] when empty).`);
+        const entries = array(rawResources[type], `resources.${type}`);
+        resources[type] = entries.map((entry, index) => {
+            const item = record(entry, `resources.${type}[${index}]`);
+            assertKeys(item, new Set(["id", "version", "path"]), `resources.${type}[${index}]`);
+            const resource = {
+                id: requiredString(item, "id", `resources.${type}[${index}]`),
+                version: requiredString(item, "version", `resources.${type}[${index}]`),
+                path: requiredString(item, "path", `resources.${type}[${index}]`),
+            };
+            validateResourcePath(resource.path, `resources.${type}[${index}].path`);
             if (!resourceExists(resource.path))
                 throw new Error(`Package resource path does not exist: ${resource.path}`);
-        }
+            return resource;
+        });
+        if (new Set(resources[type].map(({ id: resourceId }) => resourceId)).size !==
+            resources[type].length)
+            throw new Error(`Package resource identifiers in '${type}' must be unique.`);
     }
-    if (!resources.skills.length &&
-        !resources.rules.length &&
-        !resources.agents.length &&
-        !resources.hooks.length &&
-        !resources.templates.length)
+    if (!RESOURCE_TYPES.some((type) => resources[type].length))
         throw new Error("Package resources must contain at least one resource.");
+    const provenance = record(root.provenance, "provenance");
+    assertKeys(provenance, new Set(["source", "checksum"]), "provenance");
+    const provenanceSource = requiredString(provenance, "source", "provenance");
+    const checksum = optionalString(provenance, "checksum", "provenance");
+    const policies = root.policies === undefined
+        ? undefined
+        : array(root.policies, "policies").map((entry, index) => {
+            const policy = record(entry, `policies[${index}]`);
+            assertKeys(policy, new Set(["id", "value"]), `policies[${index}]`);
+            return {
+                id: requiredString(policy, "id", `policies[${index}]`),
+                value: requiredString(policy, "value", `policies[${index}]`),
+            };
+        });
+    const engines = root.engines === undefined ? undefined : stringRecord(root.engines, "engines");
+    const provides = root.provides === undefined ? undefined : parseProvides(root.provides);
+    const targets = root.targets === undefined ? undefined : stringArray(root.targets, "targets");
     return {
         schema: 1,
-        id: scalar(content, "id"),
-        version: scalar(content, "version"),
-        provider: scalar(content, "provider"),
-        source: scalar(content, "source"),
+        id,
+        version,
+        provider,
+        source,
         resources,
-        dependencies: list(content, "dependencies"),
-        permissions: list(content, "permissions"),
-        provenance: {
-            source: nestedScalar(content, "source") || scalar(content, "source"),
-            ...(nestedScalar(content, "checksum") ? { checksum: nestedScalar(content, "checksum") } : {}),
-        },
-        policies: parsePolicies(content),
-        ...(nestedScalar(content, "ai_workflow")
-            ? { engines: { ai_workflow: nestedScalar(content, "ai_workflow") } }
-            : {}),
-        ...(list(content, "targets").length ? { targets: list(content, "targets") } : {}),
+        dependencies: stringArray(root.dependencies, "dependencies"),
+        permissions: stringArray(root.permissions, "permissions"),
+        provenance: { source: provenanceSource, ...(checksum ? { checksum } : {}) },
+        ...(policies ? { policies } : {}),
+        ...(engines ? { engines } : {}),
+        ...(provides ? { provides } : {}),
+        ...(targets ? { targets } : {}),
     };
 }
-function resourceSection(content, type) {
-    return content.match(new RegExp(`^  ${type}:\\n([\\s\\S]*?)(?=^\\w|\\s*$)`, "m"))?.[1] ?? "";
+export function validateResourcePath(path, field = "resource path") {
+    if (path.startsWith("/") ||
+        path.includes("\\") ||
+        path.includes(":") ||
+        path.split("/").some((part) => !part || part === "." || part === ".."))
+        throw new Error(`Package field '${field}' must be a normalized relative path.`);
 }
-function parsePolicies(content) {
-    const section = content.match(/policies:\n((?:\s{2}- .*\n?)+)/)?.[1] ?? "";
-    return [...section.matchAll(/id:\s*([^,]+),\s*value:\s*([^ }]+)/g)].map((match) => ({
-        id: match[1].trim(),
-        value: match[2].trim(),
-    }));
+function record(value, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`Package field '${field}' must be a mapping.`);
+    return value;
+}
+function array(value, field) {
+    if (!Array.isArray(value))
+        throw new Error(`Package field '${field}' must be a list (use [] when empty).`);
+    return value;
 }
-function scalar(content, key) {
-    return (content
-        .match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]
-        ?.replaceAll('"', "")
-        .trim() ?? "");
+function requiredString(value, key, parent = "manifest") {
+    const result = value[key];
+    if (typeof result !== "string" || !result.trim())
+        throw new Error(`Package field '${parent === "manifest" ? key : `${parent}.${key}`}' must be a non-empty string.`);
+    return result.trim();
 }
-function nestedScalar(content, key) {
-    return (content
-        .match(new RegExp(`^\\s{2,}${key}:\\s*(.+)$`, "m"))?.[1]
-        ?.replaceAll('"', "")
-        .trim() ?? "");
+function optionalString(value, key, parent) {
+    if (value[key] === undefined)
+        return undefined;
+    return requiredString(value, key, parent);
+}
+function stringArray(value, field) {
+    return array(value, field).map((entry, index) => {
+        if (typeof entry !== "string" || !entry.trim())
+            throw new Error(`Package field '${field}[${index}]' must be a non-empty string.`);
+        return entry.trim();
+    });
+}
+function stringRecord(value, field) {
+    const result = record(value, field);
+    return Object.fromEntries(Object.entries(result).map(([key, entry]) => {
+        if (typeof entry !== "string" || !entry.trim())
+            throw new Error(`Package field '${field}.${key}' must be a non-empty string.`);
+        return [key, entry.trim()];
+    }));
 }
-function list(content, key) {
-    const value = scalar(content, key);
-    return value === "[]"
-        ? []
-        : value
-            .replace(/^\[|\]$/g, "")
-            .split(",")
-            .map((item) => item.trim())
-            .filter(Boolean);
+function parseProvides(value) {
+    const result = record(value, "provides");
+    for (const key of Object.keys(result))
+        if (!RESOURCE_TYPES.includes(key))
+            throw new Error(`Package provides section '${key}' is not supported.`);
+    return Object.fromEntries(Object.entries(result).map(([key, entries]) => [key, stringArray(entries, `provides.${key}`)]));
 }
-function parseResources(content, type) {
-    const section = resourceSection(content, type);
-    return [...section.matchAll(/id:\s*([\w-]+), version:\s*([\d.]+), path:\s*([^ }]+)/g)].map((match) => ({ id: match[1], version: match[2], path: match[3] }));
+function assertKeys(value, allowed, field) {
+    for (const key of Object.keys(value))
+        if (!allowed.has(key))
+            throw new Error(`Package field '${field}.${key}' is not supported.`);
 }

package/dist/package-integrity.d.ts

@@ -1,8 +1,12 @@
+import { type PackageContract } from "./package-contract.js";
+import type { FileSystem } from "./types.js";
 export type PackageProvenance = {
     checksum: string;
     signature?: string;
     signer?: string;
 };
 export type SignatureVerifier = (content: string, signature: string, signer?: string) => boolean;
-export declare function checksumPackage(content: string): string;
+export declare function checksumPackage(content: string | Uint8Array): string;
+/** Hash the exact package manifest and all declared resource bytes using a stable, framed format. */
+export declare function checksumPackageSnapshot(manifest: Uint8Array, pkg: PackageContract, root: string, fs: FileSystem, manifestPath?: string): string;
 export declare function verifyPackageProvenance(content: string, provenance: PackageProvenance, verifySignature?: SignatureVerifier): void;

package/dist/package-integrity.js

@@ -1,6 +1,61 @@
 import { createHash } from "node:crypto";
+import { validateResourcePath } from "./package-contract.js";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 export function checksumPackage(content) {
-    return createHash("sha256").update(content, "utf8").digest("hex");
+    const hash = createHash("sha256");
+    if (typeof content === "string")
+        hash.update(content, "utf8");
+    else
+        hash.update(content);
+    return hash.digest("hex");
+}
+/** Hash the exact package manifest and all declared resource bytes using a stable, framed format. */
+export function checksumPackageSnapshot(manifest, pkg, root, fs, manifestPath = "package.yaml") {
+    validateResourcePath(manifestPath, "manifest path");
+    const files = [
+        { path: manifestPath, bytes: manifest },
+    ];
+    const paths = new Set([manifestPath]);
+    for (const resources of Object.values(pkg.resources)) {
+        for (const resource of resources) {
+            validateResourcePath(resource.path);
+            if (paths.has(resource.path))
+                throw new Error(`Package resource path is duplicated: ${resource.path}`);
+            paths.add(resource.path);
+            const absolutePath = resolve(root, resource.path);
+            const rel = relative(resolve(root), absolutePath);
+            if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+                throw new Error(`Package resource path escapes its package: ${resource.path}`);
+            if (!fs.exists(absolutePath))
+                throw new Error(`Package resource path does not exist: ${resource.path}`);
+            if (fs.pathType && fs.pathType(absolutePath) !== "file")
+                throw new Error(`Package resource must be a regular file: ${resource.path}`);
+            if (fs.realpath) {
+                const realRoot = fs.realpath(root);
+                const realPath = fs.realpath(absolutePath);
+                const realRelative = relative(realRoot, realPath);
+                if (realRelative === ".." ||
+                    realRelative.startsWith(`..${sep}`) ||
+                    isAbsolute(realRelative))
+                    throw new Error(`Package resource path escapes its package: ${resource.path}`);
+            }
+            const bytes = fs.readBytes
+                ? fs.readBytes(absolutePath)
+                : Buffer.from(fs.read(absolutePath), "utf8");
+            files.push({ path: resource.path, bytes });
+        }
+    }
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const hash = createHash("sha256").update("aiw-package-snapshot-v1\0", "utf8");
+    for (const file of files) {
+        const name = Buffer.from(file.path, "utf8");
+        const nameLength = Buffer.alloc(4);
+        nameLength.writeUInt32BE(name.length);
+        const size = Buffer.alloc(8);
+        size.writeBigUInt64BE(BigInt(file.bytes.byteLength));
+        hash.update(nameLength).update(name).update(size).update(file.bytes);
+    }
+    return `sha256-${hash.digest("hex")}`;
 }
 export function verifyPackageProvenance(content, provenance, verifySignature) {
     const actual = checksumPackage(content);

package/dist/providers.d.ts

@@ -5,6 +5,7 @@ export type PackageSource = {
 export type LoadedPackageSource = PackageSource & {
     root: string;
     manifest: string;
+    manifestBytes?: Uint8Array;
     release(): void;
 };
 export interface PackageProvider {
@@ -17,4 +18,5 @@ export interface PackageSourceLoader {
 export declare const localProvider: PackageProvider;
 export declare const gitProvider: PackageProvider;
 export declare function resolveProvider(source: string, root: string): PackageSource;
+export declare function requiresExternalNetwork(source: PackageSource): boolean;
 export declare const nodePackageSourceLoader: PackageSourceLoader;

package/dist/providers.js

@@ -10,11 +10,13 @@ export const localProvider = {
     }),
 };
 export const gitProvider = {
-    canResolve: (source) => source.startsWith("git+") ||
+    canResolve: (source) => /^git\+(?:https?|ssh|git|file):\/\//i.test(source) ||
         source.startsWith("git@") ||
         source.startsWith("file://") ||
-        /^https?:\/\//.test(source) ||
-        source.endsWith(".git"),
+        /^ssh:\/\//i.test(source) ||
+        /^git:\/\//i.test(source) ||
+        /^https?:\/\//i.test(source) ||
+        (source.endsWith(".git") && !/^[a-z][a-z\d+.-]*:\/\//i.test(source)),
     normalize: (source) => ({ provider: "git", source }),
 };
 export function resolveProvider(source, root) {
@@ -23,6 +25,22 @@ export function resolveProvider(source, root) {
         throw new Error(`Unsupported package source: ${source}`);
     return provider.normalize(source, root);
 }
+export function requiresExternalNetwork(source) {
+    if (source.provider !== "git")
+        return false;
+    const normalized = source.source.startsWith("git+") ? source.source.slice(4) : source.source;
+    if (/^file:\/\//i.test(normalized))
+        return false;
+    if (isAbsolute(normalized) ||
+        normalized.startsWith("./") ||
+        normalized.startsWith("../") ||
+        normalized.startsWith(".\\") ||
+        normalized.startsWith("..\\") ||
+        /^[a-z]:[\\/]/i.test(normalized))
+        return false;
+    // Any remaining Git transport/reference is treated as external unless it is an explicit file path.
+    return true;
+}
 export const nodePackageSourceLoader = {
     load(source, projectRoot) {
         const normalized = resolveProvider(source, projectRoot);
@@ -34,10 +52,12 @@ export const nodePackageSourceLoader = {
             const manifestPath = isDirectory ? join(packageRoot, "package.yaml") : normalized.source;
             if (!existsSync(manifestPath))
                 throw new Error(`Package manifest does not exist: ${manifestPath}`);
+            const manifestBytes = readFileSync(manifestPath);
             return {
                 ...normalized,
                 root: packageRoot,
-                manifest: readFileSync(manifestPath, "utf8"),
+                manifest: manifestBytes.toString("utf8"),
+                manifestBytes,
                 release() { },
             };
         }
@@ -52,10 +72,12 @@ export const nodePackageSourceLoader = {
             const manifestPath = join(checkout, "package.yaml");
             if (!existsSync(manifestPath))
                 throw new Error("Git package does not contain package.yaml.");
+            const manifestBytes = readFileSync(manifestPath);
             return {
                 ...normalized,
                 root: checkout,
-                manifest: readFileSync(manifestPath, "utf8"),
+                manifest: manifestBytes.toString("utf8"),
+                manifestBytes,
                 release: () => rmSync(checkout, { recursive: true, force: true }),
             };
         }

package/dist/recommendations.d.ts

@@ -1,4 +1,9 @@
 import type { ProjectProfile } from "./profile.js";
+import type { ResourceType } from "./package-contract.js";
+export type RecommendedResource = {
+    type: ResourceType;
+    id: string;
+};
 export type CapabilityRecommendation = {
     id: string;
     provider: string;
@@ -7,6 +12,8 @@ export type CapabilityRecommendation = {
     evidence: string[];
     permissions: string[];
     conflicts: string[];
+    resources: RecommendedResource[];
 };
 export declare function recommendCapabilities(profile: ProjectProfile): CapabilityRecommendation[];
+export declare function resourcesForCapabilities(ids: string[]): RecommendedResource[];
 export declare function serializeRecommendations(items: CapabilityRecommendation[], selected?: string[]): string;