commandmate 0.11.3 → 0.12.0

package/dist/server/src/lib/skills/json-schema.js

@@ -0,0 +1,365 @@
+"use strict";
+/* eslint-disable no-restricted-syntax -- `description` here is JSON Schema documentation
+   published to Skill authors and validators, not UI copy: it must stay in the schema's own
+   language and is never rendered through t(). */
+/**
+ * JSON Schema documents for the Skills distribution contract (Issue #1228)
+ *
+ * These are the publishable, language-neutral form of the contract: a Skill
+ * author or a CI job outside CommandMate can validate a manifest without
+ * running TypeScript. Inside CommandMate the authority is
+ * `src/lib/skills/schema.ts`; the parity test in
+ * `tests/unit/lib/skills/json-schema-parity.test.ts` keeps the two from
+ * drifting.
+ *
+ * @module lib/skills/json-schema
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_RECEIPT_JSON_SCHEMA = exports.SKILL_CATALOG_JSON_SCHEMA = exports.SKILL_MANIFEST_JSON_SCHEMA = void 0;
+const constants_1 = require("../../lib/skills/constants");
+const types_1 = require("../../lib/cli-tools/types");
+const semver_1 = require("../../lib/skills/semver");
+const DRAFT = 'https://json-schema.org/draft/2020-12/schema';
+const BASE_ID = 'https://commandmate.dev/schemas/skills';
+const source = (pattern) => pattern.source;
+const schemaVersionProperty = {
+    const: constants_1.SKILL_SCHEMA_VERSION,
+    description: 'Contract version. Consumers reject any other value.',
+};
+const providerDef = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['name'],
+    properties: {
+        name: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_NAME_MAX_LENGTH },
+        url: { type: 'string', format: 'uri', pattern: '^https://' },
+        contact: { type: 'string', minLength: 1, maxLength: 200 },
+    },
+};
+const agentCompatibilityDef = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['agent', 'support', 'evidence'],
+    properties: {
+        agent: { type: 'string', enum: [...types_1.CLI_TOOL_IDS] },
+        support: { type: 'string', enum: [...constants_1.SKILL_AGENT_SUPPORT_VALUES] },
+        evidence: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_EVIDENCE_MAX_LENGTH },
+    },
+};
+const compatibilityDef = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['commandmate', 'agents'],
+    properties: {
+        commandmate: {
+            type: 'string',
+            minLength: 1,
+            maxLength: 100,
+            description: 'AND-combined comparator list, e.g. ">=0.11.0 <1.0.0".',
+        },
+        agents: { type: 'array', maxItems: 20, items: { $ref: '#/$defs/agentCompatibility' } },
+    },
+};
+const sourceRefDef = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['repository', 'ref', 'commit'],
+    properties: {
+        repository: { type: 'string', pattern: source(constants_1.REPOSITORY_SLUG_PATTERN) },
+        ref: { type: 'string', pattern: source(constants_1.GIT_REF_PATTERN) },
+        commit: {
+            type: 'string',
+            pattern: source(constants_1.GIT_COMMIT_SHA_PATTERN),
+            description: 'Resolved commit SHA. The trusted source coordinate.',
+        },
+    },
+};
+const sha256Property = {
+    type: 'string',
+    pattern: source(constants_1.SHA256_HEX_PATTERN),
+    description: 'Lowercase hex SHA-256.',
+};
+const declaredPermissionsProperty = {
+    type: 'array',
+    maxItems: constants_1.SKILL_DECLARED_PERMISSIONS.length,
+    uniqueItems: true,
+    items: { type: 'string', enum: [...constants_1.SKILL_DECLARED_PERMISSIONS] },
+    description: 'Publisher declaration only. Not an enforcement boundary.',
+};
+const riskProperty = { type: 'string', enum: [...constants_1.SKILL_RISK_LEVELS] };
+const payloadPathProperty = {
+    type: 'string',
+    minLength: 1,
+    maxLength: constants_1.SKILL_PATH_MAX_LENGTH,
+    description: 'POSIX relative path inside the Skill root. No "..", no absolute path.',
+};
+/** JSON Schema for `commandmate.skill.yaml`. */
+exports.SKILL_MANIFEST_JSON_SCHEMA = {
+    $schema: DRAFT,
+    $id: `${BASE_ID}/manifest-v${constants_1.SKILL_SCHEMA_VERSION}.json`,
+    title: 'CommandMate Skill manifest',
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'schema_version',
+        'id',
+        'name',
+        'version',
+        'summary',
+        'description',
+        'capabilities',
+        'expected_outcomes',
+        'provider',
+        'license',
+        'compatibility',
+        'requirements',
+        'declared_permissions',
+        'declared_risk',
+        'risk_rationale',
+        'files',
+    ],
+    properties: {
+        schema_version: schemaVersionProperty,
+        id: { type: 'string', pattern: source(constants_1.SKILL_ID_PATTERN), maxLength: constants_1.SKILL_ID_MAX_LENGTH },
+        name: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_NAME_MAX_LENGTH },
+        version: { type: 'string', pattern: source(semver_1.SEMVER_2_PATTERN) },
+        summary: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_SUMMARY_MAX_LENGTH },
+        description: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_DESCRIPTION_MAX_LENGTH },
+        capabilities: {
+            type: 'array',
+            minItems: 1,
+            maxItems: constants_1.SKILL_BULLET_MAX_COUNT,
+            items: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_BULLET_MAX_LENGTH },
+        },
+        expected_outcomes: {
+            type: 'array',
+            minItems: 1,
+            maxItems: constants_1.SKILL_BULLET_MAX_COUNT,
+            items: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_BULLET_MAX_LENGTH },
+        },
+        provider: { $ref: '#/$defs/provider' },
+        license: { type: 'string', pattern: source(constants_1.SPDX_LICENSE_PATTERN) },
+        homepage: { type: 'string', pattern: '^https://' },
+        keywords: {
+            type: 'array',
+            maxItems: constants_1.SKILL_KEYWORDS_MAX_COUNT,
+            items: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_KEYWORD_MAX_LENGTH },
+        },
+        compatibility: { $ref: '#/$defs/compatibility' },
+        requirements: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['commands', 'network_hosts'],
+            properties: {
+                commands: {
+                    type: 'array',
+                    maxItems: constants_1.SKILL_COMMANDS_MAX_COUNT,
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['name'],
+                        properties: {
+                            name: { type: 'string', minLength: 1, maxLength: 64 },
+                            version_range: { type: 'string', minLength: 1, maxLength: 100 },
+                        },
+                    },
+                },
+                network_hosts: {
+                    type: 'array',
+                    maxItems: constants_1.SKILL_NETWORK_HOSTS_MAX_COUNT,
+                    items: { type: 'string', pattern: source(constants_1.NETWORK_HOST_PATTERN) },
+                },
+            },
+        },
+        declared_permissions: declaredPermissionsProperty,
+        declared_risk: riskProperty,
+        risk_rationale: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_RATIONALE_MAX_LENGTH },
+        files: {
+            type: 'array',
+            maxItems: constants_1.SKILL_FILES_MAX_COUNT,
+            description: 'Payload files excluding commandmate.skill.yaml itself and directory entries.',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path', 'sha256', 'size', 'kind', 'executable', 'script'],
+                properties: {
+                    path: payloadPathProperty,
+                    sha256: sha256Property,
+                    size: { type: 'integer', minimum: 0, maximum: constants_1.SKILL_FILE_MAX_SIZE },
+                    kind: { type: 'string', enum: [...constants_1.SKILL_FILE_KINDS] },
+                    executable: { type: 'boolean' },
+                    script: { type: 'boolean' },
+                },
+            },
+        },
+    },
+    $defs: {
+        provider: providerDef,
+        compatibility: compatibilityDef,
+        agentCompatibility: agentCompatibilityDef,
+    },
+};
+/** JSON Schema for the Catalog document. */
+exports.SKILL_CATALOG_JSON_SCHEMA = {
+    $schema: DRAFT,
+    $id: `${BASE_ID}/catalog-v${constants_1.SKILL_SCHEMA_VERSION}.json`,
+    title: 'CommandMate Skill catalog',
+    type: 'object',
+    additionalProperties: false,
+    required: ['schema_version', 'entries'],
+    properties: {
+        schema_version: schemaVersionProperty,
+        entries: {
+            type: 'array',
+            maxItems: constants_1.SKILL_CATALOG_ENTRIES_MAX_COUNT,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['id', 'name', 'summary', 'provider', 'license', 'latest', 'versions'],
+                properties: {
+                    id: { type: 'string', pattern: source(constants_1.SKILL_ID_PATTERN), maxLength: constants_1.SKILL_ID_MAX_LENGTH },
+                    name: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_NAME_MAX_LENGTH },
+                    summary: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_SUMMARY_MAX_LENGTH },
+                    provider: { $ref: '#/$defs/provider' },
+                    license: { type: 'string', pattern: source(constants_1.SPDX_LICENSE_PATTERN) },
+                    homepage: { type: 'string', pattern: '^https://' },
+                    keywords: {
+                        type: 'array',
+                        maxItems: constants_1.SKILL_KEYWORDS_MAX_COUNT,
+                        items: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_KEYWORD_MAX_LENGTH },
+                    },
+                    latest: { type: 'string', pattern: source(semver_1.SEMVER_2_PATTERN) },
+                    versions: {
+                        type: 'array',
+                        minItems: 1,
+                        maxItems: constants_1.SKILL_CATALOG_VERSIONS_MAX_COUNT,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: [
+                                'version',
+                                'changelog',
+                                'published_at',
+                                'source',
+                                'artifact',
+                                'compatibility',
+                                'declared_risk',
+                            ],
+                            properties: {
+                                version: { type: 'string', pattern: source(semver_1.SEMVER_2_PATTERN) },
+                                changelog: { type: 'string', minLength: 1, maxLength: constants_1.SKILL_CHANGELOG_MAX_LENGTH },
+                                published_at: { type: 'string', pattern: source(constants_1.RFC3339_UTC_PATTERN) },
+                                source: { $ref: '#/$defs/sourceRef' },
+                                artifact: {
+                                    type: 'object',
+                                    additionalProperties: false,
+                                    required: ['asset_name', 'url', 'sha256', 'size', 'content_type', 'format'],
+                                    properties: {
+                                        asset_name: {
+                                            type: 'string',
+                                            minLength: 1,
+                                            maxLength: 200,
+                                            description: '<skill-id>-<version>.tar.gz',
+                                        },
+                                        url: { type: 'string', pattern: '^https://' },
+                                        sha256: sha256Property,
+                                        size: { type: 'integer', minimum: 1, maximum: constants_1.SKILL_ARTIFACT_MAX_SIZE },
+                                        content_type: { const: constants_1.SKILL_ARTIFACT_CONTENT_TYPE },
+                                        format: { const: constants_1.SKILL_ARTIFACT_FORMAT },
+                                    },
+                                },
+                                compatibility: { $ref: '#/$defs/compatibility' },
+                                declared_risk: riskProperty,
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+    $defs: {
+        provider: providerDef,
+        compatibility: compatibilityDef,
+        agentCompatibility: agentCompatibilityDef,
+        sourceRef: sourceRefDef,
+    },
+};
+/** JSON Schema for the deterministic install receipt. */
+exports.SKILL_RECEIPT_JSON_SCHEMA = {
+    $schema: DRAFT,
+    $id: `${BASE_ID}/receipt-v${constants_1.SKILL_SCHEMA_VERSION}.json`,
+    title: 'CommandMate Skill install receipt',
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'schema_version',
+        'skill_id',
+        'version',
+        'install_root',
+        'source',
+        'artifact',
+        'files',
+        'declared_risk',
+        'computed_risk',
+        'effective_risk',
+        'declared_permissions',
+        'agent_compatibility',
+    ],
+    properties: {
+        schema_version: schemaVersionProperty,
+        skill_id: { type: 'string', pattern: source(constants_1.SKILL_ID_PATTERN), maxLength: constants_1.SKILL_ID_MAX_LENGTH },
+        version: { type: 'string', pattern: source(semver_1.SEMVER_2_PATTERN) },
+        install_root: {
+            type: 'string',
+            description: 'Repository-relative .agents/skills/<skill-id>. Never a machine-absolute path.',
+        },
+        install_roots: {
+            type: 'array',
+            maxItems: constants_1.SKILL_INSTALL_ROOT_PREFIXES.length,
+            description: 'Optional (#1460): every repository-relative root the package was placed into, primary first. Absent for a single-root install.',
+            items: { type: 'string', maxLength: 200 },
+        },
+        source: { $ref: '#/$defs/sourceRef' },
+        artifact: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['asset_name', 'sha256', 'size', 'format'],
+            description: 'No url: download URLs may be signed and are treated as secrets.',
+            properties: {
+                asset_name: { type: 'string', minLength: 1, maxLength: 200 },
+                sha256: sha256Property,
+                size: { type: 'integer', minimum: 1, maximum: constants_1.SKILL_ARTIFACT_MAX_SIZE },
+                format: { const: constants_1.SKILL_ARTIFACT_FORMAT },
+            },
+        },
+        files: {
+            type: 'array',
+            maxItems: constants_1.SKILL_FILES_MAX_COUNT,
+            description: 'Sorted by path ascending so receipts are byte-reproducible.',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path', 'sha256', 'size', 'executable'],
+                properties: {
+                    path: payloadPathProperty,
+                    sha256: sha256Property,
+                    size: { type: 'integer', minimum: 0, maximum: constants_1.SKILL_FILE_MAX_SIZE },
+                    executable: { type: 'boolean' },
+                },
+            },
+        },
+        declared_risk: riskProperty,
+        computed_risk: riskProperty,
+        effective_risk: { ...riskProperty, description: 'max(declared_risk, computed_risk).' },
+        declared_permissions: declaredPermissionsProperty,
+        agent_compatibility: {
+            type: 'array',
+            maxItems: 20,
+            items: { $ref: '#/$defs/agentCompatibility' },
+        },
+    },
+    $defs: {
+        sourceRef: sourceRefDef,
+        agentCompatibility: agentCompatibilityDef,
+    },
+};

package/dist/server/src/lib/skills/operation-audit.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Minimal Skill operation audit (Issue #1234, Phase 1)
+ *
+ * Append-only writes to `skill_operations`. Every install/uninstall lands one
+ * row per outcome, carrying the source coordinates that make the change
+ * traceable to an immutable commit and artifact digest, plus the actor and the
+ * typed result.
+ *
+ * Two properties are load-bearing:
+ * - **Append-only** is enforced by database triggers (migration v44), so a
+ *   later bug cannot rewrite the log. `recordSkillOperationAudit` only inserts.
+ * - **Redaction** happens on the way in, not on the way out, so a signed URL or
+ *   a home directory path never reaches the table in the first place.
+ *
+ * @module lib/skills/operation-audit
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSkillOperationAuditInput = buildSkillOperationAuditInput;
+exports.recordSkillOperationAudit = recordSkillOperationAudit;
+exports.getSkillOperationAuditByOperationId = getSkillOperationAuditByOperationId;
+exports.listSkillOperationAudit = listSkillOperationAudit;
+const crypto_1 = require("crypto");
+const operation_store_1 = require("../../lib/skills/operation-store");
+function mapRow(row) {
+    return {
+        id: row.id,
+        operationId: row.operation_id,
+        idempotencyKey: row.idempotency_key,
+        bindingHash: row.binding_hash,
+        operation: row.operation,
+        state: row.state,
+        result: row.result,
+        actorType: row.actor_type,
+        actorId: row.actor_id,
+        worktreeId: row.worktree_id,
+        skillId: row.skill_id,
+        skillVersion: row.skill_version,
+        sourceOrigin: row.source_origin,
+        sourceRepository: row.source_repository,
+        sourceRef: row.source_ref,
+        sourceCommit: row.source_commit,
+        artifactSha256: row.artifact_sha256,
+        errorCode: row.error_code,
+        errorMessage: row.error_message,
+        recordedAt: row.recorded_at,
+    };
+}
+const SELECT_COLUMNS = `
+  id, operation_id, idempotency_key, binding_hash, operation, state, result,
+  actor_type, actor_id, worktree_id, skill_id, skill_version,
+  source_origin, source_repository, source_ref, source_commit, artifact_sha256,
+  error_code, error_message, recorded_at
+`;
+/**
+ * Build an audit input from a journal entry, so the two records cannot drift.
+ * The journal already holds the actor, target, source and typed error.
+ */
+function buildSkillOperationAuditInput(entry, result, recordedAt) {
+    return {
+        operationId: entry.operationId,
+        idempotencyKey: entry.idempotencyKey,
+        bindingHash: entry.bindingHash,
+        operation: entry.operation,
+        state: entry.state,
+        result,
+        actorType: entry.actor.type,
+        actorId: entry.actor.id,
+        worktreeId: entry.target.worktreeId,
+        skillId: entry.target.skillId,
+        skillVersion: entry.target.version,
+        sourceOrigin: entry.source?.origin ?? null,
+        sourceRepository: entry.source?.repository ?? null,
+        sourceRef: entry.source?.ref ?? null,
+        sourceCommit: entry.source?.commit ?? null,
+        artifactSha256: entry.source?.artifactSha256 ?? null,
+        errorCode: entry.error?.code ?? null,
+        errorMessage: entry.error?.message ?? null,
+        recordedAt,
+    };
+}
+/** Append one audit event. Never updates: repeated outcomes add rows. */
+function recordSkillOperationAudit(db, input) {
+    const record = {
+        ...input,
+        id: (0, crypto_1.randomUUID)(),
+        errorMessage: input.errorMessage === null ? null : (0, operation_store_1.redactSkillOperationText)(input.errorMessage),
+        recordedAt: input.recordedAt ?? Date.now(),
+    };
+    db.prepare(`INSERT INTO skill_operations (
+      id, operation_id, idempotency_key, binding_hash, operation, state, result,
+      actor_type, actor_id, worktree_id, skill_id, skill_version,
+      source_origin, source_repository, source_ref, source_commit, artifact_sha256,
+      error_code, error_message, recorded_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(record.id, record.operationId, record.idempotencyKey, record.bindingHash, record.operation, record.state, record.result, record.actorType, record.actorId, record.worktreeId, record.skillId, record.skillVersion, record.sourceOrigin, record.sourceRepository, record.sourceRef, record.sourceCommit, record.artifactSha256, record.errorCode, record.errorMessage, record.recordedAt);
+    return record;
+}
+/** Audit trail of one operation, oldest first. */
+function getSkillOperationAuditByOperationId(db, operationId) {
+    const rows = db
+        .prepare(`SELECT ${SELECT_COLUMNS} FROM skill_operations
+       WHERE operation_id = ? ORDER BY recorded_at ASC, id ASC`)
+        .all(operationId);
+    return rows.map(mapRow);
+}
+/** Audit trail for one Skill in one worktree, newest first. */
+function listSkillOperationAudit(db, filter) {
+    const limit = filter.limit ?? 100;
+    const rows = (filter.skillId === undefined
+        ? db
+            .prepare(`SELECT ${SELECT_COLUMNS} FROM skill_operations
+             WHERE worktree_id = ? ORDER BY recorded_at DESC, id DESC LIMIT ?`)
+            .all(filter.worktreeId, limit)
+        : db
+            .prepare(`SELECT ${SELECT_COLUMNS} FROM skill_operations
+             WHERE worktree_id = ? AND skill_id = ?
+             ORDER BY recorded_at DESC, id DESC LIMIT ?`)
+            .all(filter.worktreeId, filter.skillId, limit));
+    return rows.map(mapRow);
+}