@schalkneethling/calavera-artifact-core 0.2.0-next.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Schalk Neethling
+
+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,3 @@
+# Artifact core
+
+Workspace boundary for artifact catalog, resolution, verification, target adaptation, and installation APIs. Product behavior is introduced in Phases 3 and 4.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@schalkneethling/calavera-artifact-core",
+  "version": "0.2.0-next.1",
+  "description": "Catalog and package resolution primitives for Calavera artifacts.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/schalkneethling/create-project-calavera.git",
+    "directory": "packages/artifact-core"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/catalog.js",
+    "./node": "./src/node.js",
+    "./registry": "./src/registry.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "pacote": "22.0.0",
+    "semver": "7.8.5",
+    "@schalkneethling/calavera-agent-technical-devils-advocate": "^0.2.0-next.1",
+    "@schalkneethling/calavera-hook-block-dangerous-commands": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-calavera": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-code-review": "^0.2.0-next.1",
+    "@schalkneethling/calavera-hook-auto-approve-safe-commands": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-frontend-engineering": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-frontend-security": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-frontend-testing": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-github-goal-issue-triage": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-css-tokens": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-more-secure-dependabot-config": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-npm-trusted-publishing-github-workflow": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-project-goal": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-refined-plan-mode": "^0.2.0-next.1",
+    "@schalkneethling/calavera-skill-npm-publishing-best-practices": "^0.2.0-next.1"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/src/catalog.js

@@ -0,0 +1,139 @@
+// @ts-check
+import manifest1 from "@schalkneethling/calavera-skill-calavera" with { type: "json" };
+import manifest2 from "@schalkneethling/calavera-skill-code-review" with { type: "json" };
+import manifest3 from "@schalkneethling/calavera-skill-css-tokens" with { type: "json" };
+import manifest4 from "@schalkneethling/calavera-skill-frontend-engineering" with { type: "json" };
+import manifest5 from "@schalkneethling/calavera-skill-frontend-security" with { type: "json" };
+import manifest6 from "@schalkneethling/calavera-skill-frontend-testing" with { type: "json" };
+import manifest7 from "@schalkneethling/calavera-skill-github-goal-issue-triage" with { type: "json" };
+import manifest8 from "@schalkneethling/calavera-skill-more-secure-dependabot-config" with { type: "json" };
+import manifest9 from "@schalkneethling/calavera-skill-npm-publishing-best-practices" with { type: "json" };
+import manifest10 from "@schalkneethling/calavera-skill-npm-trusted-publishing-github-workflow" with { type: "json" };
+import manifest11 from "@schalkneethling/calavera-skill-project-goal" with { type: "json" };
+import manifest12 from "@schalkneethling/calavera-skill-refined-plan-mode" with { type: "json" };
+import manifest13 from "@schalkneethling/calavera-hook-auto-approve-safe-commands" with { type: "json" };
+import manifest14 from "@schalkneethling/calavera-hook-block-dangerous-commands" with { type: "json" };
+import manifest15 from "@schalkneethling/calavera-agent-technical-devils-advocate" with { type: "json" };
+import package1 from "@schalkneethling/calavera-skill-calavera/package.json" with { type: "json" };
+import package2 from "@schalkneethling/calavera-skill-code-review/package.json" with { type: "json" };
+import package3 from "@schalkneethling/calavera-skill-css-tokens/package.json" with { type: "json" };
+import package4 from "@schalkneethling/calavera-skill-frontend-engineering/package.json" with { type: "json" };
+import package5 from "@schalkneethling/calavera-skill-frontend-security/package.json" with { type: "json" };
+import package6 from "@schalkneethling/calavera-skill-frontend-testing/package.json" with { type: "json" };
+import package7 from "@schalkneethling/calavera-skill-github-goal-issue-triage/package.json" with { type: "json" };
+import package8 from "@schalkneethling/calavera-skill-more-secure-dependabot-config/package.json" with { type: "json" };
+import package9 from "@schalkneethling/calavera-skill-npm-publishing-best-practices/package.json" with { type: "json" };
+import package10 from "@schalkneethling/calavera-skill-npm-trusted-publishing-github-workflow/package.json" with { type: "json" };
+import package11 from "@schalkneethling/calavera-skill-project-goal/package.json" with { type: "json" };
+import package12 from "@schalkneethling/calavera-skill-refined-plan-mode/package.json" with { type: "json" };
+import package13 from "@schalkneethling/calavera-hook-auto-approve-safe-commands/package.json" with { type: "json" };
+import package14 from "@schalkneethling/calavera-hook-block-dangerous-commands/package.json" with { type: "json" };
+import package15 from "@schalkneethling/calavera-agent-technical-devils-advocate/package.json" with { type: "json" };
+
+export const DEFAULT_ARTIFACT_TARGET = "claude-code";
+
+const packageVersions = new Map([
+  ["@schalkneethling/calavera-skill-calavera", package1.version],
+  ["@schalkneethling/calavera-skill-code-review", package2.version],
+  ["@schalkneethling/calavera-skill-css-tokens", package3.version],
+  ["@schalkneethling/calavera-skill-frontend-engineering", package4.version],
+  ["@schalkneethling/calavera-skill-frontend-security", package5.version],
+  ["@schalkneethling/calavera-skill-frontend-testing", package6.version],
+  ["@schalkneethling/calavera-skill-github-goal-issue-triage", package7.version],
+  ["@schalkneethling/calavera-skill-more-secure-dependabot-config", package8.version],
+  ["@schalkneethling/calavera-skill-npm-publishing-best-practices", package9.version],
+  ["@schalkneethling/calavera-skill-npm-trusted-publishing-github-workflow", package10.version],
+  ["@schalkneethling/calavera-skill-project-goal", package11.version],
+  ["@schalkneethling/calavera-skill-refined-plan-mode", package12.version],
+  ["@schalkneethling/calavera-hook-auto-approve-safe-commands", package13.version],
+  ["@schalkneethling/calavera-hook-block-dangerous-commands", package14.version],
+  ["@schalkneethling/calavera-agent-technical-devils-advocate", package15.version],
+]);
+
+export const artifactCatalog = Object.freeze([
+  artifact(manifest1, "@schalkneethling/calavera-skill-calavera", "skills/calavera"),
+  artifact(manifest2, "@schalkneethling/calavera-skill-code-review", "skills/code-review"),
+  artifact(manifest3, "@schalkneethling/calavera-skill-css-tokens", "skills/css-tokens"),
+  artifact(
+    manifest4,
+    "@schalkneethling/calavera-skill-frontend-engineering",
+    "skills/frontend-engineering",
+  ),
+  artifact(
+    manifest5,
+    "@schalkneethling/calavera-skill-frontend-security",
+    "skills/frontend-security",
+  ),
+  artifact(
+    manifest6,
+    "@schalkneethling/calavera-skill-frontend-testing",
+    "skills/frontend-testing",
+  ),
+  artifact(
+    manifest7,
+    "@schalkneethling/calavera-skill-github-goal-issue-triage",
+    "skills/github-goal-issue-triage",
+  ),
+  artifact(
+    manifest8,
+    "@schalkneethling/calavera-skill-more-secure-dependabot-config",
+    "skills/more-secure-dependabot-config",
+  ),
+  artifact(
+    manifest9,
+    "@schalkneethling/calavera-skill-npm-publishing-best-practices",
+    "skills/npm-publishing-best-practices",
+  ),
+  artifact(
+    manifest10,
+    "@schalkneethling/calavera-skill-npm-trusted-publishing-github-workflow",
+    "skills/npm-trusted-publishing-github-workflow",
+  ),
+  artifact(manifest11, "@schalkneethling/calavera-skill-project-goal", "skills/project-goal"),
+  artifact(
+    manifest12,
+    "@schalkneethling/calavera-skill-refined-plan-mode",
+    "skills/refined-plan-mode",
+  ),
+  artifact(
+    manifest13,
+    "@schalkneethling/calavera-hook-auto-approve-safe-commands",
+    "hooks/auto-approve-safe-commands",
+  ),
+  artifact(
+    manifest14,
+    "@schalkneethling/calavera-hook-block-dangerous-commands",
+    "hooks/block-dangerous-commands",
+  ),
+  artifact(
+    manifest15,
+    "@schalkneethling/calavera-agent-technical-devils-advocate",
+    "agents/technical-devils-advocate.md",
+  ),
+]);
+
+/**
+ * @param {{ id: string, type: string, displayName: string, payload: string, [key: string]: unknown }} manifest
+ * @param {string} packageName
+ * @param {string} legacyPath
+ */
+function artifact(manifest, packageName, legacyPath) {
+  return Object.freeze({
+    ...manifest,
+    packageName,
+    version: packageVersions.get(packageName),
+    legacyPath,
+    group: manifest.type === "skill" ? "Skills" : manifest.type === "hook" ? "Hooks" : "Agents",
+    defaultTarget: manifest.type === "skill" ? undefined : DEFAULT_ARTIFACT_TARGET,
+  });
+}
+
+/** @param {string} id */
+export function artifactForId(id) {
+  return artifactCatalog.find((artifact) => artifact.id === id);
+}
+
+/** @param {string} path */
+export function artifactForLegacyPath(path) {
+  return artifactCatalog.find((artifact) => artifact.legacyPath === path);
+}

package/src/node.js

@@ -0,0 +1,16 @@
+// @ts-check
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { artifactForId, artifactForLegacyPath } from "./catalog.js";
+
+/** @param {string} idOrLegacyPath */
+export function artifactPayloadPath(idOrLegacyPath) {
+  const artifact = artifactForId(idOrLegacyPath) ?? artifactForLegacyPath(idOrLegacyPath);
+  if (!artifact) {
+    throw new Error(`Unknown Calavera artifact: ${idOrLegacyPath}.`);
+  }
+
+  const manifestUrl = import.meta.resolve(artifact.packageName);
+  return join(dirname(fileURLToPath(manifestUrl)), artifact.payload);
+}

package/src/registry.js

@@ -0,0 +1,142 @@
+// @ts-check
+import { createHash } from "node:crypto";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+import pacote from "pacote";
+import semver from "semver";
+
+import { artifactForId } from "./catalog.js";
+
+const TAGS = new Set(["latest", "next"]);
+
+/** @param {{ id: string, tag?: string, version?: string, cache: string, offline?: boolean }} request */
+export async function resolveArtifactPackage(request) {
+  const artifact = artifactForId(request.id);
+  if (!artifact) throw new Error(`Unknown Calavera artifact: ${request.id}.`);
+  const tag = request.tag ?? "latest";
+  if (!TAGS.has(tag)) throw new Error("Artifact release tag must be latest or next.");
+  if (request.version && !semver.valid(request.version)) {
+    throw new Error(`Artifact version must be exact semver: ${request.version}.`);
+  }
+
+  const manifest = await pacote.manifest(`${artifact.packageName}@${request.version ?? tag}`, {
+    cache: request.cache,
+    offline: request.offline,
+    fullMetadata: true,
+  });
+  if (manifest.name !== artifact.packageName || !semver.valid(manifest.version)) {
+    throw new Error(`Resolved package identity mismatch for ${artifact.packageName}.`);
+  }
+  if (!manifest.dist?.tarball || !manifest.dist.integrity) {
+    throw new Error(`Registry metadata for ${artifact.packageName} is missing tarball integrity.`);
+  }
+
+  return {
+    artifact,
+    packageName: artifact.packageName,
+    version: manifest.version,
+    resolved: manifest.dist.tarball,
+    integrity: String(manifest.dist.integrity),
+    tag,
+    cache: request.cache,
+    offline: request.offline ?? false,
+  };
+}
+
+/**
+ * @param {{ artifact: { id: string, type: string, packageName: string }, packageName: string, version: string, resolved: string, integrity?: string, tag: string, cache: string, offline: boolean }} resolution
+ * @param {string} destination
+ * @param {string} cliVersion
+ */
+export async function extractArtifactPackage(resolution, destination, cliVersion) {
+  await pacote.extract(resolution.resolved, destination, {
+    cache: resolution.cache,
+    integrity: resolution.integrity,
+    offline: resolution.offline,
+  });
+
+  const packageJson = JSON.parse(await readFile(join(destination, "package.json"), "utf8"));
+  const manifest = JSON.parse(await readFile(join(destination, "calavera-artifact.json"), "utf8"));
+  if (packageJson.name !== resolution.packageName || packageJson.version !== resolution.version) {
+    throw new Error("Extracted package identity does not match registry metadata.");
+  }
+
+  validateArtifactManifest(manifest, resolution.artifact, cliVersion);
+  const payloadPath = safePayloadPath(destination, manifest.payload);
+  const payloadStats = await stat(payloadPath);
+  if ((manifest.type === "agent") !== payloadStats.isFile()) {
+    throw new Error(`Artifact payload kind does not match manifest type ${manifest.type}.`);
+  }
+
+  return { manifest, payloadPath, payloadHash: await hashArtifactPayload(payloadPath) };
+}
+
+/**
+ * @param {Record<string, unknown>} manifest
+ * @param {{ id: string, type: string, packageName: string }} artifact
+ * @param {string} cliVersion
+ */
+function validateArtifactManifest(manifest, artifact, cliVersion) {
+  if (
+    manifest.schemaVersion !== 1 ||
+    manifest.id !== artifact.id ||
+    manifest.type !== artifact.type ||
+    typeof manifest.payload !== "string" ||
+    !manifest.payload ||
+    !manifest.compatibility ||
+    typeof manifest.compatibility !== "object"
+  ) {
+    throw new Error(`Invalid artifact manifest for ${artifact.packageName}.`);
+  }
+  const compatibility = /** @type {Record<string, unknown>} */ (manifest.compatibility).calavera;
+  if (typeof compatibility !== "string" || !semver.satisfies(cliVersion, compatibility)) {
+    throw new Error(
+      `${artifact.packageName} is not compatible with create-project-calavera ${cliVersion}.`,
+    );
+  }
+}
+
+/** @param {string} root @param {string} payload */
+function safePayloadPath(root, payload) {
+  const payloadPath = resolve(root, payload);
+  const relativePath = relative(root, payloadPath);
+  if (!relativePath || relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error("Artifact payload must stay inside its package.");
+  }
+  return payloadPath;
+}
+
+/** @param {string} path */
+export async function hashArtifactPayload(path) {
+  const payloadStats = await stat(path);
+  const hash = createHash("sha256");
+  if (payloadStats.isFile()) {
+    hash.update(await readFile(path));
+    return hash.digest("hex");
+  }
+  for (const entry of await payloadFiles(path)) {
+    hash.update(entry).update("\0");
+    if (!entry.endsWith("/")) {
+      hash.update(await readFile(join(path, entry))).update("\0");
+    }
+  }
+  return hash.digest("hex");
+}
+
+/**
+ * @param {string} root
+ * @param {string} [directory]
+ * @returns {Promise<string[]>}
+ */
+async function payloadFiles(root, directory = root) {
+  const files = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(`${relative(root, path)}/`);
+      files.push(...(await payloadFiles(root, path)));
+    } else if (entry.isFile()) files.push(relative(root, path));
+  }
+  return files.sort();
+}