@shrkcrft/inspector 0.1.0-alpha.1

package/dist/agent-contract-templates.js

@@ -0,0 +1,346 @@
+/**
+ * Reusable agent-contract templates.
+ *
+ * `buildAgentContract` derives a contract from inspection + intent. Templates
+ * are reusable starting points that capture *intent classes* — "release task",
+ * "public-API change", "polyglot service change", etc. They are deterministic
+ * dictionaries; rendering merges them with the live contract output.
+ */
+import { ContractFileRuleKind, ContractFileRuleSeverity, } from "./contract-file-rule.js";
+import { RoleId } from "./role-views.js";
+import { AgentContractMode } from "./agent-contract.js";
+export const AGENT_CONTRACT_TEMPLATE_SCHEMA = 'sharkcraft.agent-contract-template/v1';
+export var AgentContractTemplateMatch;
+(function (AgentContractTemplateMatch) {
+    AgentContractTemplateMatch["Exact"] = "exact";
+    AgentContractTemplateMatch["Partial"] = "partial";
+    AgentContractTemplateMatch["None"] = "none";
+})(AgentContractTemplateMatch || (AgentContractTemplateMatch = {}));
+const t = (input) => ({
+    schema: AGENT_CONTRACT_TEMPLATE_SCHEMA,
+    ...input,
+});
+const RULE_ERR = (pattern, kind, reason) => ({
+    pattern,
+    kind,
+    reason,
+    severity: ContractFileRuleSeverity.Error,
+});
+export const AI_AGENT_SAFE_CHANGE_TEMPLATE = t({
+    id: 'ai-agent-safe-change',
+    title: 'AI agent — safe change',
+    description: 'Baseline contract for an AI agent making a focused, low-blast-radius change.',
+    role: RoleId.AiAgent,
+    mode: AgentContractMode.Conservative,
+    defaultForbiddenFilesDetailed: [
+        RULE_ERR('.git/**', ContractFileRuleKind.Glob, 'Never write to git internals.'),
+        RULE_ERR('.npmrc', ContractFileRuleKind.Exact, 'Registry credentials surface.'),
+        RULE_ERR('package.json', ContractFileRuleKind.Exact, 'Do not bump version or change deps without approval.'),
+        RULE_ERR('CHANGELOG.md', ContractFileRuleKind.Exact, 'Release manager approval required.'),
+    ],
+    defaultRequiredValidations: ['bun test', 'shrk doctor'],
+    defaultHumanApprovalGates: ['Human approves before `shrk apply`.'],
+    defaultDefinitionOfDone: [
+        'Tests pass (`bun test`).',
+        '`shrk doctor` is clean.',
+        'No source-write happened from MCP.',
+    ],
+    defaultRollbackPlan: [
+        'Revert the most recent `shrk apply` via `git revert <sha>`.',
+        'Re-run `bun test` and `shrk doctor`.',
+    ],
+    appliesWhen: {
+        roles: [RoleId.AiAgent],
+    },
+});
+export const PUBLIC_API_CHANGE_TEMPLATE = t({
+    id: 'public-api-change',
+    title: 'Public-API change',
+    description: 'Contract for changes touching exported public surfaces / plugin-api.',
+    role: RoleId.Developer,
+    mode: AgentContractMode.Balanced,
+    defaultForbiddenFilesDetailed: [
+        RULE_ERR('packages/plugin-api/**/internal/**', ContractFileRuleKind.Glob, 'Never touch internal/* from a public-API change.'),
+        RULE_ERR('.git/**', ContractFileRuleKind.Glob, 'Never write to git internals.'),
+    ],
+    defaultRequiredValidations: ['bun test', 'shrk doctor', 'shrk check boundaries', 'shrk api report --diff'],
+    defaultHumanApprovalGates: [
+        'API reviewer approves the surface diff before `shrk apply`.',
+        'Update CHANGELOG.md with public-API change notes.',
+    ],
+    defaultDefinitionOfDone: [
+        'API report is updated and reviewed.',
+        'No removed/renamed exports without a deprecation notice.',
+        'Boundary check passes.',
+    ],
+    defaultRollbackPlan: [
+        'Revert the API change PR.',
+        'Re-run `shrk api report --diff` to confirm clean surface.',
+    ],
+    appliesWhen: {
+        taskKeywords: ['public api', 'plugin-api', 'exported', 'public surface'],
+    },
+});
+export const RELEASE_TASK_TEMPLATE = t({
+    id: 'release-task',
+    title: 'Release task',
+    description: 'Contract for a release / publish flow. Forbids bypassing the gate.',
+    role: RoleId.ReleaseManager,
+    mode: AgentContractMode.Conservative,
+    defaultForbiddenFilesDetailed: [
+        RULE_ERR('package.json', ContractFileRuleKind.Exact, 'Bump version only inside `bun run release:bump-versions`.'),
+        RULE_ERR('CHANGELOG.md', ContractFileRuleKind.Exact, 'Manual edits only after preflight passes.'),
+        RULE_ERR('.npmrc', ContractFileRuleKind.Exact, 'Never commit registry credentials.'),
+    ],
+    defaultRequiredValidations: [
+        'bun run release:preflight',
+        'shrk release readiness --strict',
+        'shrk safety audit --deep',
+    ],
+    defaultHumanApprovalGates: [
+        'Release manager runs `bun run release:preflight` locally before tagging.',
+        'Publish step is human-only (`bun run publish:packages`).',
+    ],
+    defaultDefinitionOfDone: [
+        'Preflight is green.',
+        'Readiness verdict is ready (strict).',
+        'Tag pushed only after human verification.',
+    ],
+    defaultRollbackPlan: [
+        'Delete the bad tag (`git tag -d` + `git push --delete`).',
+        'Re-run preflight on the previous commit.',
+    ],
+    appliesWhen: {
+        taskKeywords: ['release', 'publish', 'tag', 'cut a version', 'preflight'],
+        intentKinds: ['release'],
+        roles: [RoleId.ReleaseManager],
+    },
+});
+export const MIGRATION_TASK_TEMPLATE = t({
+    id: 'migration-task',
+    title: 'Migration task',
+    description: 'Contract for a multi-step migration / refactor with explicit readiness gates.',
+    role: RoleId.Developer,
+    mode: AgentContractMode.Balanced,
+    defaultForbiddenFilesDetailed: [
+        RULE_ERR('package.json', ContractFileRuleKind.Exact, 'Do not bump dep versions mid-migration.'),
+        RULE_ERR('.git/**', ContractFileRuleKind.Glob, 'Never write to git internals.'),
+    ],
+    defaultRequiredValidations: ['bun test', 'shrk doctor', 'shrk migration readiness'],
+    defaultHumanApprovalGates: [
+        'Migration readiness verdict must be "ready" before applying the migration plan.',
+    ],
+    defaultDefinitionOfDone: [
+        'All migration steps reviewed.',
+        'Readiness is ready.',
+        'Tests + boundary check pass after each step.',
+    ],
+    defaultRollbackPlan: [
+        'Revert the migration commit.',
+        'Re-run `shrk migration readiness` to confirm rollback.',
+    ],
+    appliesWhen: {
+        taskKeywords: ['migrate', 'migration', 'refactor', 'rename', 'rip out', 'retire'],
+        intentKinds: ['migration', 'refactor'],
+    },
+});
+export const SECURITY_SENSITIVE_CHANGE_TEMPLATE = t({
+    id: 'security-sensitive-change',
+    title: 'Security-sensitive change',
+    description: 'Contract for changes touching auth / signing / secrets / packs.',
+    role: RoleId.Security,
+    mode: AgentContractMode.Conservative,
+    defaultForbiddenFilesDetailed: [
+        RULE_ERR('.git/**', ContractFileRuleKind.Glob, 'Never write to git internals.'),
+        RULE_ERR('.npmrc', ContractFileRuleKind.Exact, 'Registry credentials surface.'),
+        RULE_ERR('**/manifest.signed.json', ContractFileRuleKind.Glob, 'Re-sign via `shrk packs sign`, never hand-edit.'),
+        RULE_ERR('**/.env*', ContractFileRuleKind.Glob, 'Secrets must not be committed.'),
+    ],
+    defaultRequiredValidations: [
+        'shrk safety audit --deep',
+        'shrk packs doctor --require-signatures',
+        'bun test',
+    ],
+    defaultHumanApprovalGates: [
+        'Security reviewer approves changes to auth / signing / secrets / packs.',
+        'Re-sign affected packs with the documented secret.',
+    ],
+    defaultDefinitionOfDone: [
+        'Safety audit is green.',
+        'Affected packs re-signed.',
+        'No new write-style MCP tools.',
+    ],
+    defaultRollbackPlan: [
+        'Revert the change PR.',
+        'Re-sign packs with the previous secret.',
+        'Re-run `shrk safety audit --deep`.',
+    ],
+    appliesWhen: {
+        taskKeywords: ['auth', 'signing', 'sign', 'secret', 'pack', 'security', 'credentials', 'hmac'],
+        roles: [RoleId.Security],
+    },
+});
+export const POLYGLOT_SERVICE_CHANGE_TEMPLATE = t({
+    id: 'polyglot-service-change',
+    title: 'Polyglot service change',
+    description: 'Contract for changes in a repo with multiple language profiles (Java / C# / Python / Go / Rust + TS).',
+    role: RoleId.Developer,
+    mode: AgentContractMode.Balanced,
+    defaultForbiddenFilesDetailed: [
+        RULE_ERR('.git/**', ContractFileRuleKind.Glob, 'Never write to git internals.'),
+        RULE_ERR('target/**', ContractFileRuleKind.Glob, 'Build outputs (Java/Rust) — should not be committed.'),
+        RULE_ERR('bin/**', ContractFileRuleKind.Glob, 'Build outputs.'),
+        RULE_ERR('obj/**', ContractFileRuleKind.Glob, '.NET build outputs.'),
+        RULE_ERR('__pycache__/**', ContractFileRuleKind.Glob, 'Python bytecode cache.'),
+        RULE_ERR('node_modules/**', ContractFileRuleKind.Glob, 'JS dep tree.'),
+    ],
+    defaultRequiredValidations: [
+        'shrk languages detect',
+        'shrk doctor',
+        'shrk check boundaries',
+    ],
+    defaultHumanApprovalGates: [
+        'Each language touched runs its native test suite (`mvn test` / `dotnet test` / `pytest` / `go test ./...` / `cargo test`).',
+    ],
+    defaultDefinitionOfDone: [
+        'Each touched language profile has passing tests.',
+        'Boundary check is green across languages.',
+        'No bytecode / build outputs in the diff.',
+    ],
+    defaultRollbackPlan: [
+        'Revert the change PR.',
+        'Re-run language-native test suites for each touched language.',
+    ],
+    appliesWhen: {
+        taskKeywords: ['java', 'maven', 'gradle', 'csharp', 'dotnet', 'python', 'pytest', 'golang', ' go ', 'rust', 'cargo', 'polyglot'],
+    },
+});
+/**
+ * Project-specific contract templates
+ * now live in packs and are merged via `loadAllContractTemplates`. The
+ * engine ships only generic templates here.
+ */
+export const ALL_CONTRACT_TEMPLATES = [
+    AI_AGENT_SAFE_CHANGE_TEMPLATE,
+    PUBLIC_API_CHANGE_TEMPLATE,
+    RELEASE_TASK_TEMPLATE,
+    MIGRATION_TASK_TEMPLATE,
+    SECURITY_SENSITIVE_CHANGE_TEMPLATE,
+    POLYGLOT_SERVICE_CHANGE_TEMPLATE,
+];
+export function listContractTemplates() {
+    return ALL_CONTRACT_TEMPLATES;
+}
+export function getContractTemplate(id) {
+    return ALL_CONTRACT_TEMPLATES.find((t) => t.id === id) ?? null;
+}
+/** Score each template against a task + optional role. Highest score wins. */
+export function recommendContractTemplate(task, role, intentKind) {
+    const lower = task.toLowerCase();
+    const out = [];
+    for (const tpl of ALL_CONTRACT_TEMPLATES) {
+        let score = 0;
+        const reasons = [];
+        const aw = tpl.appliesWhen;
+        if (aw.taskKeywords && aw.taskKeywords.length > 0) {
+            const hits = aw.taskKeywords.filter((k) => lower.includes(k.toLowerCase()));
+            if (hits.length > 0) {
+                score += hits.length * 2;
+                reasons.push(`keyword: ${hits.join(', ')}`);
+            }
+        }
+        if (aw.intentKinds && intentKind && aw.intentKinds.includes(intentKind)) {
+            score += 3;
+            reasons.push(`intent: ${intentKind}`);
+        }
+        if (aw.roles && role && aw.roles.includes(role)) {
+            score += 2;
+            reasons.push(`role: ${role}`);
+        }
+        if (score > 0) {
+            const match = score >= 4 ? AgentContractTemplateMatch.Exact : AgentContractTemplateMatch.Partial;
+            out.push({ template: tpl, match, reason: reasons.join('; ') });
+        }
+    }
+    return out.sort((a, b) => (b.match === AgentContractTemplateMatch.Exact ? 1 : 0) - (a.match === AgentContractTemplateMatch.Exact ? 1 : 0));
+}
+export function renderContractTemplateMarkdown(t, task) {
+    let out = `# Contract template: ${t.title}\n\n`;
+    if (task)
+        out += `- **task**: ${task}\n`;
+    out += `- **id**: \`${t.id}\`\n`;
+    out += `- **role**: ${t.role}\n`;
+    out += `- **mode**: ${t.mode}\n\n`;
+    out += `${t.description}\n\n`;
+    if (t.defaultForbiddenFilesDetailed.length > 0) {
+        out += `## Forbidden files\n| Pattern | Kind | Reason |\n| --- | --- | --- |\n`;
+        for (const r of t.defaultForbiddenFilesDetailed)
+            out += `| \`${r.pattern}\` | ${r.kind} | ${r.reason ?? ''} |\n`;
+        out += `\n`;
+    }
+    if (t.defaultRequiredValidations.length > 0) {
+        out += `## Required validations\n`;
+        for (const v of t.defaultRequiredValidations)
+            out += `- \`${v}\`\n`;
+        out += `\n`;
+    }
+    if (t.defaultHumanApprovalGates.length > 0) {
+        out += `## Human approval gates\n`;
+        for (const g of t.defaultHumanApprovalGates)
+            out += `- ${g}\n`;
+        out += `\n`;
+    }
+    if (t.defaultDefinitionOfDone.length > 0) {
+        out += `## Definition of done\n`;
+        for (const d of t.defaultDefinitionOfDone)
+            out += `- ${d}\n`;
+        out += `\n`;
+    }
+    if (t.defaultRollbackPlan.length > 0) {
+        out += `## Rollback plan\n`;
+        for (const r of t.defaultRollbackPlan)
+            out += `- ${r}\n`;
+        out += `\n`;
+    }
+    return out;
+}
+export function renderContractTemplateText(t, task) {
+    let out = `=== Contract template: ${t.title} ===\n`;
+    if (task)
+        out += `  task     ${task}\n`;
+    out += `  id       ${t.id}\n`;
+    out += `  role     ${t.role}\n`;
+    out += `  mode     ${t.mode}\n\n`;
+    out += `${t.description}\n\n`;
+    if (t.defaultForbiddenFilesDetailed.length > 0) {
+        out += `Forbidden files:\n`;
+        for (const r of t.defaultForbiddenFilesDetailed)
+            out += `  • [${r.kind}] ${r.pattern} — ${r.reason ?? ''}\n`;
+        out += `\n`;
+    }
+    if (t.defaultRequiredValidations.length > 0) {
+        out += `Required validations:\n`;
+        for (const v of t.defaultRequiredValidations)
+            out += `  • ${v}\n`;
+        out += `\n`;
+    }
+    if (t.defaultHumanApprovalGates.length > 0) {
+        out += `Human approval gates:\n`;
+        for (const g of t.defaultHumanApprovalGates)
+            out += `  • ${g}\n`;
+        out += `\n`;
+    }
+    if (t.defaultDefinitionOfDone.length > 0) {
+        out += `Definition of done:\n`;
+        for (const d of t.defaultDefinitionOfDone)
+            out += `  • ${d}\n`;
+        out += `\n`;
+    }
+    if (t.defaultRollbackPlan.length > 0) {
+        out += `Rollback plan:\n`;
+        for (const r of t.defaultRollbackPlan)
+            out += `  • ${r}\n`;
+        out += `\n`;
+    }
+    return out;
+}

package/dist/agent-contract.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Agent contract.
+ *
+ * Given a task, role, and mode, compose a deterministic safety contract
+ * combining existing systems (intent, task risk, impact, ownership,
+ * boundaries, policies, playbooks, constructs, templates, role views).
+ *
+ * Read-only. No model calls, no telemetry, no embeddings.
+ */
+import { type IChangeIntent } from './change-intent.js';
+import { type ITaskRiskReport } from './task-risk.js';
+import { RoleId } from './role-views.js';
+import { type IContractFileRule } from './contract-file-rule.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const AGENT_CONTRACT_SCHEMA = "sharkcraft.agent-contract/v1";
+export declare enum AgentContractMode {
+    Conservative = "conservative",
+    Balanced = "balanced",
+    Aggressive = "aggressive"
+}
+export interface IBuildAgentContractOptions {
+    files?: readonly string[];
+    since?: string;
+    staged?: boolean;
+    role?: RoleId | string;
+    mode?: AgentContractMode | string;
+}
+export interface IAgentContract {
+    schema: typeof AGENT_CONTRACT_SCHEMA;
+    generatedAt: string;
+    task: string;
+    intent: IChangeIntent;
+    taskRisk: ITaskRiskReport;
+    role: RoleId;
+    mode: AgentContractMode;
+    allowedFiles: readonly string[];
+    forbiddenFiles: readonly string[];
+    /** Structured file rules. Empty when contract only uses legacy strings. */
+    allowedFilesDetailed?: readonly IContractFileRule[];
+    forbiddenFilesDetailed?: readonly IContractFileRule[];
+    allowedCommands: readonly string[];
+    forbiddenCommands: readonly string[];
+    requiredValidations: readonly string[];
+    requiredReviews: readonly string[];
+    requiredPlanReviews: readonly string[];
+    humanApprovalGates: readonly string[];
+    rollbackPlan: readonly string[];
+    definitionOfDone: readonly string[];
+    relevantConstructs: readonly string[];
+    relevantPolicies: readonly string[];
+    relevantBoundaries: readonly string[];
+    relevantPlaybooks: readonly string[];
+    relevantTemplates: readonly string[];
+    likelyTests: readonly string[];
+    impactedAreas: readonly string[];
+    publicApiRisks: readonly string[];
+    ownershipReview: readonly string[];
+    recommendedNextCommand: string;
+    safetyNotes: readonly string[];
+}
+export declare function buildAgentContract(task: string, inspection: ISharkcraftInspection, options?: IBuildAgentContractOptions): Promise<IAgentContract>;
+export declare function renderAgentContractText(c: IAgentContract): string;
+export declare function renderAgentContractMarkdown(c: IAgentContract): string;
+export declare function renderAgentContractHtml(c: IAgentContract): string;
+//# sourceMappingURL=agent-contract.d.ts.map

package/dist/agent-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-contract.d.ts","sourceRoot":"","sources":["../src/agent-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAEpE,oBAAY,iBAAiB;IAC3B,YAAY,iBAAiB;IAC7B,QAAQ,aAAa;IACrB,UAAU,eAAe;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,qBAAqB,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,iBAAiB,CAAC;IACxB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,2EAA2E;IAC3E,oBAAoB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpD,sBAAsB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACtD,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAqXD,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,cAAc,CAAC,CA0GzB;AAOD,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CA8BjE;AAOD,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CA+BrE;AAWD,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAGjE"}