@microck/canonfig 2.0.0

package/dist/domain/recipe-versions.js

@@ -0,0 +1,297 @@
+import { Schema } from "effect";
+import { isNpmRegistryPackageName } from "./npm-package-spec.js";
+export const RecipeMethod = Schema.Literals([
+    "npm",
+    "pnpm",
+    "bun",
+    "brew",
+    "homebrew",
+    "apt",
+    "winget",
+    "uv",
+    "cargo",
+    "source",
+]);
+/** Recipe methods that the current deterministic process executor may run. */
+export const AutomaticRecipeMethod = Schema.Literals([
+    "npm",
+    "pnpm",
+    "bun",
+    "brew",
+    "homebrew",
+    "apt",
+    "winget",
+    "uv",
+    "cargo",
+]);
+/** Canonical source metadata retained for reviewed package recipes. */
+export const RecipeSourceMetadata = Schema.Struct({
+    source: Schema.NonEmptyString,
+    integrity: Schema.optional(Schema.NonEmptyString),
+});
+/**
+ * A reviewed Python package index. The full URL is retained because private
+ * repositories commonly scope their simple API below an origin.
+ */
+export const RecipeIndexPolicy = Schema.Struct({
+    url: Schema.NonEmptyString,
+    reviewedBy: Schema.NonEmptyString,
+    reviewedAt: Schema.NonEmptyString,
+});
+export const defaultPythonIndex = "https://pypi.org/simple";
+const hasUnsafeIndexUrlCharacter = (value) => [...value].some((character) => {
+    const code = character.codePointAt(0) ?? 0;
+    return code <= 0x20
+        || (code >= 0x7f && code <= 0x9f)
+        || "\"'<>".includes(character);
+});
+/** Canonicalize a reviewed full simple-index URL without widening its scope. */
+export const canonicalRecipeIndexUrl = (value) => {
+    if (value.trim() !== value
+        || value.includes("#")
+        || value.includes("\\")
+        || hasUnsafeIndexUrlCharacter(value))
+        return undefined;
+    try {
+        const parsed = new URL(value);
+        if (parsed.protocol !== "https:"
+            || parsed.username.length > 0
+            || parsed.password.length > 0
+            || parsed.hash.length > 0
+            || parsed.pathname === "/"
+            || !/(?:^|\/)simple\/?$/u.test(parsed.pathname))
+            return undefined;
+        parsed.pathname = parsed.pathname.replace(/\/$/u, "");
+        return parsed.href;
+    }
+    catch {
+        return undefined;
+    }
+};
+const npmVersion = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+const homebrewVersion = /^[0-9A-Za-z][0-9A-Za-z.+_~+-]*$/u;
+const wingetVersion = /^[0-9A-Za-z][0-9A-Za-z.+_~-]*$/u;
+const uvVersion = /^[0-9A-Za-z][0-9A-Za-z!+._-]*$/u;
+const cargoVersion = npmVersion;
+const aptVersion = /^[0-9A-Za-z][0-9A-Za-z.+:~_+-]*$/u;
+const sourceRevision = /^[0-9A-Za-z][0-9A-Za-z._~/-]*$/u;
+const unsafePackageArgument = /[\p{Cc}\s%=&|<>`"'$()[\]{}]/u;
+const unsafeVersionCharacter = /[\p{Cc}\s%/@?#=\\;&|<>`"'$()[\]{}]/u;
+const isSafeScalar = (value, unsafe) => value.length > 0
+    && value === value.trim()
+    && !value.startsWith("-")
+    && !value.startsWith("+")
+    && !unsafe.test(value);
+export const isSafePackageArgument = (value) => isSafeScalar(value, unsafePackageArgument);
+const versionPatternFor = (method) => {
+    switch (method) {
+        case "npm":
+        case "pnpm":
+        case "bun":
+            return npmVersion;
+        case "brew":
+        case "homebrew":
+            return homebrewVersion;
+        case "winget":
+            return wingetVersion;
+        case "uv":
+            return uvVersion;
+        case "cargo":
+            return cargoVersion;
+        case "apt":
+            return aptVersion;
+        case "source":
+            return sourceRevision;
+        default:
+            return undefined;
+    }
+};
+/**
+ * Return a stable, boundary-friendly explanation when a recipe cannot be
+ * represented by the deterministic installer.
+ */
+export const recipeValidationError = (input) => {
+    const { method, package: packageName, version } = input;
+    if (!Schema.is(RecipeMethod)(method)) {
+        return `unknown installer method ${method}`;
+    }
+    if ((method === "npm" || method === "pnpm" || method === "bun")
+        && !isNpmRegistryPackageName(packageName)) {
+        return `npm-family package must be an exact registry name: ${packageName}`;
+    }
+    if (method === "source" && version === undefined) {
+        return "source recipes require an immutable revision";
+    }
+    if (method !== "source" && !isSafePackageArgument(packageName)) {
+        return `package argument is unsafe: ${packageName}`;
+    }
+    if (input.indexPolicy !== undefined) {
+        if (method !== "uv") {
+            return "recipe index policy is only supported for uv recipes";
+        }
+        const { url, reviewedBy, reviewedAt } = input.indexPolicy;
+        if (reviewedBy.trim().length === 0 || !Number.isFinite(Date.parse(reviewedAt))) {
+            return "recipe index policy requires a reviewer and valid review timestamp";
+        }
+        if (canonicalRecipeIndexUrl(url) === undefined) {
+            return "recipe index policy must be a credential-free HTTPS simple-index URL";
+        }
+    }
+    const metadata = sourceValue(input.source);
+    const integrity = metadata?.integrity ?? input.integrity;
+    const sourceVersion = ((method === "npm" || method === "pnpm" || method === "bun")
+        && version === undefined)
+        ? npmVersionFromTarballSource(packageName, metadata?.source ?? "")
+        : version;
+    if ((method === "npm" || method === "pnpm" || method === "bun")
+        && version === undefined
+        && (sourceVersion === undefined
+            || integrity === undefined)) {
+        return "npm-family registry installs require an exact version or a reviewed tarball with integrity";
+    }
+    const sourceReason = recipeSourceValidationError({
+        ...input,
+        version: sourceVersion,
+    });
+    if (sourceReason !== undefined)
+        return sourceReason;
+    if (version === undefined && sourceVersion === undefined)
+        return undefined;
+    const pattern = versionPatternFor(method);
+    if (pattern === undefined
+        || !isSafeScalar(sourceVersion, unsafeVersionCharacter)
+        || !pattern.test(sourceVersion)) {
+        return `installer ${method} cannot honor requested version ${sourceVersion}`;
+    }
+    return undefined;
+};
+/** Whether an automatic recipe lacks a version that its installer can honor. */
+export const isMissingAutomaticRecipeVersion = (input) => {
+    if (!Schema.is(AutomaticRecipeMethod)(input.method))
+        return false;
+    if (input.version !== undefined)
+        return false;
+    if (!isSafePackageArgument(input.package))
+        return false;
+    if ((input.method === "npm" || input.method === "pnpm" || input.method === "bun")
+        && !isNpmRegistryPackageName(input.package)) {
+        return false;
+    }
+    const metadata = sourceValue(input.source);
+    const integrity = metadata?.integrity ?? input.integrity;
+    const remoteSource = metadata?.source.startsWith("http:") === true
+        || metadata?.source.startsWith("https:") === true;
+    const npmFamily = input.method === "npm"
+        || input.method === "pnpm"
+        || input.method === "bun";
+    if (remoteSource && !npmFamily)
+        return false;
+    if (remoteSource && npmFamily && integrity !== undefined)
+        return false;
+    return !(npmFamily
+        && npmVersionFromTarballSource(input.package, metadata?.source ?? "") !== undefined
+        && integrity !== undefined);
+};
+const sourceValue = (source) => source === undefined
+    ? undefined
+    : Schema.is(Schema.String)(source)
+        ? { source }
+        : source;
+const isSRI = (value) => /^(?:sha256|sha512)-[A-Za-z0-9+/]+={0,2}$/u.test(value);
+const npmTarballPath = (packageName, version) => {
+    const packagePart = packageName.startsWith("@")
+        ? packageName.slice(packageName.indexOf("/") + 1)
+        : packageName;
+    return `/${packageName}/-/${packagePart}-${version}.tgz`;
+};
+export const npmVersionFromTarballSource = (packageName, source) => {
+    const packagePart = packageName.startsWith("@")
+        ? packageName.slice(packageName.indexOf("/") + 1)
+        : packageName;
+    const prefix = `https://registry.npmjs.org/${packageName}/-/${packagePart}-`;
+    if (!source.startsWith(prefix) || !source.endsWith(".tgz"))
+        return undefined;
+    const candidate = source.slice(prefix.length, -".tgz".length);
+    return npmVersion.test(candidate) ? candidate : undefined;
+};
+/**
+ * Validate the reviewed source without turning a lockfile locator into a
+ * package-manager argument. Non-URL locators remain useful evidence and are
+ * installed from the canonical registry; URL sources are only accepted for
+ * exact npm registry tarballs.
+ */
+export const recipeSourceValidationError = (input) => {
+    const metadata = sourceValue(input.source);
+    const integrity = metadata?.integrity ?? input.integrity;
+    if (input.integrity !== undefined && metadata?.integrity !== undefined) {
+        return "recipe source integrity is duplicated";
+    }
+    if (integrity !== undefined && !isSRI(integrity)) {
+        return "recipe source integrity must be a valid sha256 or sha512 SRI value";
+    }
+    if (metadata === undefined)
+        return undefined;
+    let url;
+    try {
+        url = new URL(metadata.source);
+    }
+    catch {
+        // Lockfile paths and evidence locators are not install arguments.
+        if ((input.method === "npm" || input.method === "pnpm" || input.method === "bun")
+            && integrity !== undefined) {
+            return "npm-family recipe integrity requires a canonical HTTPS registry tarball source";
+        }
+        return undefined;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        // Schemes such as lock:, package:, and file paths are evidence locators,
+        // not network sources.
+        if (/^(?:git\+|git:|ssh:|github:|gitlab:|bitbucket:|file:|link:|workspace:|npm:)/iu.test(metadata.source)) {
+            return "mutable Git or source dependency metadata is not an approved package artifact";
+        }
+        return undefined;
+    }
+    if (url.protocol !== "https:"
+        || url.username.length > 0
+        || url.password.length > 0
+        || url.search.length > 0
+        || url.hash.length > 0
+        || url.port.length > 0 && url.port !== "443") {
+        return "recipe source must be an exact HTTPS URL without credentials, redirects, query, or fragment";
+    }
+    if (input.method !== "npm"
+        && input.method !== "pnpm"
+        && input.method !== "bun"
+        && input.method !== "source") {
+        return "recipe source URLs are only supported for npm-family registry artifacts or reviewed source recipes";
+    }
+    if (input.method === "npm" || input.method === "pnpm" || input.method === "bun") {
+        const expectedSource = `https://registry.npmjs.org${npmTarballPath(input.package, input.version ?? "")}`;
+        if (input.version === undefined || metadata.source !== expectedSource) {
+            return "npm-family recipe source must be the canonical registry tarball for package and version";
+        }
+        if (url.origin !== "https://registry.npmjs.org") {
+            return "npm-family recipe source must use the canonical npm registry origin";
+        }
+        let path;
+        try {
+            path = decodeURIComponent(url.pathname);
+        }
+        catch {
+            return "npm-family recipe source has an invalid encoded path";
+        }
+        if (input.version === undefined || path !== npmTarballPath(input.package, input.version)) {
+            return "npm-family recipe source must match the exact registry tarball for package and version";
+        }
+    }
+    return undefined;
+};
+export const recipeSourceDetails = (source, integrity) => {
+    const metadata = sourceValue(source);
+    return {
+        source: metadata?.source,
+        integrity: metadata?.integrity ?? integrity,
+    };
+};
+export const isSafeRecipe = (input) => recipeValidationError(input) === undefined;
+export const isSafeSourceRevision = (value) => isSafeScalar(value, unsafeVersionCharacter) && sourceRevision.test(value);

package/dist/domain/resource.js

@@ -0,0 +1,259 @@
+import { Schema } from "effect";
+import { BlobId, ContentDigest, CredentialReference, GroupName, ResourceId, ToolId, } from "./brand.js";
+import { AutomaticRecipeMethod as AutomaticRecipeMethodSchema, RecipeSourceMetadata as RecipeSourceMetadataSchema, RecipeIndexPolicy as RecipeIndexPolicySchema, RecipeMethod as RecipeMethodSchema, recipeValidationError, } from "./recipe-versions.js";
+/**
+ * Profile Resource kinds and Apply Policies from the architecture contract.
+ * The defaults table is the single source of truth for policy-kind defaults.
+ */
+export const ResourceKind = Schema.Literals([
+    "file",
+    "directory",
+    "config",
+    "skill",
+    "tool",
+    "credential",
+    "schedule",
+]);
+export const ApplyPolicy = Schema.Literals([
+    "replace",
+    "mirror-owned",
+    "merge",
+    "replace-if-unmodified",
+    "ensure",
+    "require-local",
+]);
+/** The default Apply Policy for each resource kind, per the architecture contract. */
+export const defaultPolicyForKind = {
+    file: "replace",
+    directory: "mirror-owned",
+    config: "merge",
+    skill: "replace-if-unmodified",
+    tool: "ensure",
+    credential: "require-local",
+    schedule: "replace",
+};
+/** Which policies are compatible with which kinds. `ensure` and `require-local` are kind-specific. */
+const compatiblePolicies = {
+    file: ["replace", "replace-if-unmodified"],
+    directory: ["mirror-owned", "replace"],
+    config: ["merge", "replace"],
+    skill: ["replace-if-unmodified", "replace"],
+    tool: ["ensure"],
+    credential: ["require-local"],
+    schedule: ["replace"],
+};
+export const policyCompatibleWithKind = (kind, policy) => compatiblePolicies[kind].some((candidate) => candidate === policy);
+/** Platform selector for installation recipes and path mapping. */
+export const Platform = Schema.Literals(["linux", "macos", "windows"]);
+export const RecipeMethod = RecipeMethodSchema;
+export const AutomaticRecipeMethod = AutomaticRecipeMethodSchema;
+/**
+ * A build policy is part of the reviewed recipe contract. The default keeps
+ * package lifecycle hooks disabled. A required build policy records the
+ * bounds a future sandboxed builder would need; the current process executor
+ * deliberately escalates this mode to Human Action Required.
+ */
+export const BuildCapability = Schema.Literals([
+    "read-files",
+    "write-files",
+    "network",
+    "execute",
+]);
+export const BuildStep = Schema.Struct({
+    executable: Schema.NonEmptyString,
+    arguments: Schema.Array(Schema.String),
+});
+export const BuildPolicy = Schema.Union([
+    Schema.Struct({
+        mode: Schema.Literal("scripts-disabled"),
+    }),
+    Schema.Struct({
+        mode: Schema.Literal("required"),
+        reviewedBy: Schema.NonEmptyString,
+        reviewedAt: Schema.NonEmptyString,
+        executables: Schema.Array(Schema.NonEmptyString),
+        paths: Schema.Array(Schema.NonEmptyString),
+        origins: Schema.Array(Schema.NonEmptyString),
+        capabilities: Schema.Array(BuildCapability),
+        steps: Schema.Array(BuildStep),
+    }),
+]);
+export { RecipeSourceMetadataSchema as RecipeSourceMetadata };
+export const RecipeIndexPolicy = RecipeIndexPolicySchema;
+/**
+ * A Profile Resource: one named item of desired configuration.
+ * `spec` carries kind-specific fields decoded by `resourceSpecSchema`.
+ */
+export const GroupFilter = Schema.Struct({
+    anyOf: Schema.Array(GroupName),
+});
+export const DirectoryFile = Schema.Struct({
+    path: Schema.NonEmptyString,
+    blob: BlobId,
+    executable: Schema.Boolean,
+});
+export const FileResourceSpec = Schema.Struct({
+    kind: Schema.Literal("file"),
+    content: Schema.String,
+    digest: ContentDigest,
+    executable: Schema.Boolean,
+    symlinkTo: Schema.optional(Schema.NonEmptyString),
+});
+export const DirectoryResourceSpec = Schema.Struct({
+    kind: Schema.Literal("directory"),
+    files: Schema.Array(DirectoryFile),
+});
+export const ConfigFormat = Schema.Literals(["toml", "json", "yaml"]);
+export const ConfigValue = Schema.Union([
+    Schema.String,
+    Schema.Number,
+    Schema.Boolean,
+    Schema.Array(Schema.String),
+]);
+export const ConfigKey = Schema.Struct({
+    path: Schema.NonEmptyString,
+    value: ConfigValue,
+});
+export const ConfigResourceSpec = Schema.Struct({
+    kind: Schema.Literal("config"),
+    format: ConfigFormat,
+    keys: Schema.Array(ConfigKey),
+});
+export const SkillResourceSpec = Schema.Struct({
+    kind: Schema.Literal("skill"),
+    name: Schema.NonEmptyString,
+    files: Schema.Array(DirectoryFile),
+});
+const ToolRecipeRefSchema = Schema.Struct({
+    platform: Platform,
+    method: RecipeMethod,
+    package: Schema.NonEmptyString,
+    version: Schema.optional(Schema.NonEmptyString),
+    indexPolicy: Schema.optional(RecipeIndexPolicySchema),
+    buildPolicy: Schema.optional(BuildPolicy),
+    source: Schema.optional(Schema.Union([
+        Schema.NonEmptyString,
+        RecipeSourceMetadataSchema,
+    ])),
+});
+export const ToolRecipeRef = ToolRecipeRefSchema.check(Schema.makeFilter((recipe) => {
+    const reason = recipeValidationError(recipe);
+    return reason === undefined
+        ? undefined
+        : { path: ["version"], issue: reason };
+}));
+export const LoginRequirement = Schema.Union([
+    Schema.Struct({ required: Schema.Literal(false) }),
+    Schema.Struct({
+        required: Schema.Literal(true),
+        howTo: Schema.NonEmptyString,
+    }),
+]);
+export const ToolResourceSpec = Schema.Struct({
+    kind: Schema.Literal("tool"),
+    toolId: ToolId,
+    recipes: Schema.Array(ToolRecipeRef),
+    login: LoginRequirement,
+});
+export const CredentialResourceSpec = Schema.Struct({
+    kind: Schema.Literal("credential"),
+    reference: CredentialReference,
+});
+export const ScheduleCalendar = Schema.Union([
+    Schema.Struct({
+        type: Schema.Literal("daily"),
+        at: Schema.NonEmptyString,
+    }),
+    Schema.Struct({
+        type: Schema.Literal("weekly"),
+        days: Schema.Array(Schema.NonEmptyString),
+        at: Schema.NonEmptyString,
+    }),
+    Schema.Struct({
+        type: Schema.Literal("custom"),
+        expression: Schema.NonEmptyString,
+    }),
+]);
+export const ScheduleResourceSpec = Schema.Struct({
+    kind: Schema.Literal("schedule"),
+    calendar: ScheduleCalendar,
+    timezone: Schema.NonEmptyString,
+});
+export const ResourceSpec = Schema.Union([
+    FileResourceSpec,
+    DirectoryResourceSpec,
+    ConfigResourceSpec,
+    SkillResourceSpec,
+    ToolResourceSpec,
+    CredentialResourceSpec,
+    ScheduleResourceSpec,
+]);
+/** How to verify a resource reached its desired state. */
+export const VerificationSpec = Schema.Union([
+    Schema.Struct({
+        method: Schema.Literal("digest"),
+        digest: ContentDigest,
+    }),
+    Schema.Struct({
+        method: Schema.Literal("command"),
+        command: Schema.Array(Schema.NonEmptyString),
+        expectContains: Schema.optional(Schema.String),
+    }),
+    Schema.Struct({
+        method: Schema.Literal("executable-present"),
+        executable: Schema.NonEmptyString,
+    }),
+    Schema.Struct({
+        method: Schema.Literal("credential-present"),
+        reference: CredentialReference,
+    }),
+    Schema.Struct({
+        method: Schema.Literal("symlink"),
+        target: Schema.NonEmptyString,
+    }),
+]);
+export const ProfileResource = Schema.Struct({
+    id: ResourceId,
+    kind: ResourceKind,
+    policy: ApplyPolicy,
+    target: Schema.NonEmptyString,
+    group: Schema.optional(GroupFilter),
+    dependsOn: Schema.Array(ResourceId),
+    spec: ResourceSpec,
+    verify: VerificationSpec,
+});
+/** A discovered tool entry from the source scan, per the profile contract. */
+export const InvocationEvidence = Schema.Struct({
+    source: Schema.NonEmptyString,
+    line: Schema.Int.check(Schema.isGreaterThan(0)),
+    invocation: Schema.NonEmptyString,
+    resolvedExecutable: Schema.optional(Schema.NonEmptyString),
+    packageManager: Schema.optional(Schema.NonEmptyString),
+});
+const ToolRecipeSchema = Schema.Struct({
+    platform: Platform,
+    method: RecipeMethod,
+    package: Schema.NonEmptyString,
+    version: Schema.optional(Schema.NonEmptyString),
+    source: Schema.optional(Schema.Union([
+        Schema.NonEmptyString,
+        RecipeSourceMetadataSchema,
+    ])),
+});
+export const ToolRecipe = ToolRecipeSchema.check(Schema.makeFilter((recipe) => {
+    const reason = recipeValidationError(recipe);
+    return reason === undefined
+        ? undefined
+        : { path: ["version"], issue: reason };
+}));
+export const DiscoveredTool = Schema.Struct({
+    id: ToolId,
+    upstream: Schema.NonEmptyString,
+    evidence: Schema.Array(InvocationEvidence),
+    recipes: Schema.Array(ToolRecipe),
+    verify: Schema.Struct({
+        command: Schema.Array(Schema.NonEmptyString),
+        expectContains: Schema.optional(Schema.String),
+    }),
+    login: LoginRequirement,
+});