@stonekeep/ai 0.0.0-stage → 0.8.0

package/dist/setup.js

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { StonekeepError, collectSchemaFields, loadConfig, readDataMap } from '@stonekeep/core';
+import { parse as parseYaml } from 'yaml';
+import { diffLines, renderDiff } from './diff.js';
+import { buildSchemaMetadata } from './metadata.js';
+import { buildPrompt } from './prompt.js';
+import { renderProposal } from './render.js';
+/**
+ * `stonekeep setup`: datamap -> schema metadata (guarded) -> provider ->
+ * validated YAML -> diff -> explicit "Y" -> save. Never saves without an
+ * explicit yes, and never in a non-interactive session.
+ */
+export async function runSetup(options) {
+    const { io } = options;
+    const datamap = readDataMap(options.datamapPath);
+    const fields = collectSchemaFields(loadConfig(options.root)).fields;
+    const metadata = buildSchemaMetadata({ datamap, fields });
+    const provider = typeof options.provider === 'function' ? options.provider(metadata) : options.provider;
+    const columns = metadata.entities.reduce((n, e) => n + e.columns.length, 0);
+    io.stderr(`Sending schema metadata only (${metadata.entities.length} entities, ${columns} columns; no data values) to ${provider.name}...\n`);
+    const proposal = await provider.propose(buildPrompt(metadata));
+    let existingText = '';
+    let existing;
+    if (existsSync(options.connectorPath)) {
+        existingText = readFileSync(options.connectorPath, 'utf8');
+        const parsed = parseYaml(existingText);
+        if (typeof parsed === 'object' && parsed !== null)
+            existing = parsed;
+    }
+    const rendered = renderProposal(proposal, metadata, existing);
+    for (const w of rendered.warnings)
+        io.stderr(`warning: ${w}\n`);
+    const diff = diffLines(existingText, rendered.yaml);
+    const changed = diff.some((l) => l.op !== ' ');
+    io.stdout(`\nProposed changes to ${options.connectorPath}:\n\n`);
+    io.stdout(renderDiff(diff, io.color === true));
+    if (!changed) {
+        io.stdout('\nNo changes.\n');
+        return { saved: false, yaml: rendered.yaml, warnings: rendered.warnings, changed };
+    }
+    if (rendered.warnings.some((w) => w.startsWith('invalid:'))) {
+        throw new StonekeepError('CONFIG', 'The proposal is not a valid connector config; nothing was saved');
+    }
+    if (!io.ask) {
+        io.stdout('\nNot an interactive terminal: nothing was saved. Re-run in a terminal to confirm.\n');
+        return { saved: false, yaml: rendered.yaml, warnings: rendered.warnings, changed };
+    }
+    const answer = (await io.ask('\nSave these changes? Type Y to save, anything else to cancel: ')).trim();
+    if (answer !== 'Y' && answer !== 'y') {
+        io.stdout('Cancelled: nothing was saved.\n');
+        return { saved: false, yaml: rendered.yaml, warnings: rendered.warnings, changed };
+    }
+    writeFileSync(options.connectorPath, rendered.yaml, 'utf8');
+    io.stdout(`Saved ${options.connectorPath}. Review it, then run \`stonekeep discover\` to check it against the database.\n`);
+    return { saved: true, yaml: rendered.yaml, warnings: rendered.warnings, changed };
+}
+//# sourceMappingURL=setup.js.map

package/dist/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"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"}

package/dist/skill.d.ts

@@ -0,0 +1,5 @@
+/** SKILL.md: instructions for AI coding agents working in a repository that uses Stonekeep. */
+export declare function renderSkillMd(options?: {
+    connector?: string;
+    datamap?: string;
+}): string;

package/dist/skill.js

@@ -0,0 +1,58 @@
+/** SKILL.md: instructions for AI coding agents working in a repository that uses Stonekeep. */
+export function renderSkillMd(options = {}) {
+    const connector = options.connector ?? 'stonekeep.connector.yaml';
+    const datamap = options.datamap ?? 'stonekeep-datamap.json';
+    return `---
+name: stonekeep
+description: Use when changing database schemas, migrations, ORM models or API schemas in this repository, or when asked about personal data, GDPR/CCPA requests, data deletion, exports or staging masking. Stonekeep tracks which fields hold personal data and enforces it in CI.
+---
+
+# Stonekeep in this repository
+
+Stonekeep maps personal data (PII) in the code and runs data-subject operations (export, deletion,
+anonymization, staging masking) against the database. It helps teams manage personal data; it does
+not guarantee legal compliance, so never claim that it does.
+
+## Files
+
+| File | What it is | Who edits it |
+| --- | --- | --- |
+| \`${datamap}\` | Generated map of personal-data fields (field names only, no values) | \`stonekeep scan\` only; review diffs in PRs |
+| \`stonekeep.config.json\` | Rules, excludes, per-field overrides | Humans; you may propose changes |
+| \`${connector}\` | Database subject, relations, retention rules, masking, SaaS connectors | Humans; propose with \`stonekeep setup\` |
+
+## When you change a schema (migration, Prisma/TypeORM model, OpenAPI/JSON Schema)
+
+1. Run \`stonekeep scan\` and include the updated \`${datamap}\` in the same change.
+2. Run \`stonekeep check\`. Exit code 1 means a personal-data field is not mapped: fix it by
+   committing the regenerated datamap, or by adding an override in \`stonekeep.config.json\`
+   (\`"category"\`, or \`"ignore": true\` only if the field truly is not personal data).
+3. If you add a column that references the subject without a database foreign key (for example
+   \`requester_id\`), add it under \`tables.<table>.foreignKeys\` in \`${connector}\`, otherwise deletions
+   will miss those rows.
+4. If you add a table whose records must be kept for legal reasons (invoices, payments), add a
+   \`retain\` rule instead of letting deletions remove it.
+
+## Tools you may use
+
+- \`stonekeep scan [path]\` / \`stonekeep check [path]\`: safe, local, read-only except the datamap.
+- \`stonekeep discover\`: read-only catalog view of the configured database.
+- \`stonekeep delete --subject-env VAR\` **without** \`--apply\`: a dry run that shows what would be deleted
+  or retained, with counts only.
+- \`stonekeep mask\` **without** \`--apply\`: a dry run of the staging clone plan.
+- \`stonekeep setup\`: proposes \`${connector}\` changes from schema metadata. It shows a diff and only
+  saves after a human types Y. Do not answer that prompt yourself.
+- MCP server (\`stonekeep-mcp\`): \`scan_codebase\`, \`plan_compliance_yaml\`, \`dry_run_delete\`. There is
+  deliberately no tool that executes a deletion.
+
+## Never
+
+- Never run \`stonekeep delete --apply\`, \`stonekeep mask --apply\`, or approve a request through the
+  Stonekeep API. Destructive operations require a human and, for deletions, a second approver.
+- Never put real personal data (emails, names, ids from production) in code, tests, fixtures,
+  commit messages, issue text, or prompts. Use obviously fake values (example.com, 555 numbers).
+- Never write secrets into config files. Credentials are references such as \`env:STRIPE_API_KEY\`.
+- Never edit \`${datamap}\` by hand or delete entries to make \`stonekeep check\` pass.
+`;
+}
+//# sourceMappingURL=skill.js.map

package/dist/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,MAAM,UAAU,aAAa,CAAC,UAAoD,EAAE;IAClF,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,0BAA0B,CAAC;IAClE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,wBAAwB,CAAC;IAC5D,OAAO;;;;;;;;;;;;;;;MAeH,OAAO;;MAEP,SAAS;;;;sDAIuC,OAAO;;;;;yEAKY,SAAS;;;;;;;;;;;;oCAY9C,SAAS;;;;;;;;;;;;iBAY5B,OAAO;CACvB,CAAC;AACF,CAAC"}

package/eval/golden.json

@@ -0,0 +1,224 @@
+{
+  "$comment": "Golden set for the setup-assistant prompt: 30 schema fields (names, types and scanner classification only) with the expected masking strategy. Expected values are reviewer judgment; 'keep' means not personal data.",
+  "subject": { "table": "customers", "key": "id" },
+  "retain": ["invoices"],
+  "fields": [
+    { "entity": "customers", "field": "id", "type": "integer", "rule": null, "expected": "keep" },
+    {
+      "entity": "customers",
+      "field": "email",
+      "type": "text",
+      "rule": "email",
+      "category": "contact",
+      "expected": "email"
+    },
+    {
+      "entity": "customers",
+      "field": "first_name",
+      "type": "text",
+      "rule": "person-name",
+      "category": "identity",
+      "expected": "first-name"
+    },
+    {
+      "entity": "customers",
+      "field": "last_name",
+      "type": "text",
+      "rule": "person-name",
+      "category": "identity",
+      "expected": "last-name"
+    },
+    {
+      "entity": "customers",
+      "field": "phone",
+      "type": "varchar(32)",
+      "rule": "phone",
+      "category": "contact",
+      "expected": "phone"
+    },
+    {
+      "entity": "customers",
+      "field": "date_of_birth",
+      "type": "date",
+      "rule": "date-of-birth",
+      "category": "demographic",
+      "expected": "date"
+    },
+    {
+      "entity": "customers",
+      "field": "signup_ip",
+      "type": "inet",
+      "rule": "online-identifier",
+      "category": "online_identifier",
+      "expected": "ip"
+    },
+    {
+      "entity": "customers",
+      "field": "passport_number",
+      "type": "varchar(20)",
+      "rule": "government-id",
+      "category": "government_id",
+      "expected": "token"
+    },
+    {
+      "entity": "customers",
+      "field": "stripe_customer_id",
+      "type": "text",
+      "rule": null,
+      "expected": "token"
+    },
+    {
+      "entity": "customers",
+      "field": "created_at",
+      "type": "timestamptz",
+      "rule": null,
+      "expected": "keep"
+    },
+    {
+      "entity": "customers",
+      "field": "marketing_opt_in",
+      "type": "boolean",
+      "rule": null,
+      "expected": "keep"
+    },
+    {
+      "entity": "addresses",
+      "field": "street",
+      "type": "text",
+      "rule": "postal-address",
+      "category": "location",
+      "expected": "street"
+    },
+    {
+      "entity": "addresses",
+      "field": "city",
+      "type": "text",
+      "rule": "postal-address",
+      "category": "location",
+      "expected": "city"
+    },
+    {
+      "entity": "addresses",
+      "field": "postal_code",
+      "type": "varchar(16)",
+      "rule": "postal-address",
+      "category": "location",
+      "expected": "zip"
+    },
+    {
+      "entity": "addresses",
+      "field": "latitude",
+      "type": "numeric(9,6)",
+      "rule": "postal-address",
+      "category": "location",
+      "expected": "geo"
+    },
+    { "entity": "orders", "field": "id", "type": "integer", "rule": null, "expected": "keep" },
+    {
+      "entity": "orders",
+      "field": "customer_id",
+      "type": "integer",
+      "rule": null,
+      "expected": "keep"
+    },
+    {
+      "entity": "orders",
+      "field": "total_cents",
+      "type": "integer",
+      "rule": null,
+      "expected": "keep"
+    },
+    {
+      "entity": "orders",
+      "field": "shipping_name",
+      "type": "text",
+      "rule": "person-name",
+      "category": "identity",
+      "expected": "full-name"
+    },
+    {
+      "entity": "invoices",
+      "field": "billing_email",
+      "type": "text",
+      "rule": "email",
+      "category": "contact",
+      "expected": "email"
+    },
+    {
+      "entity": "invoices",
+      "field": "billing_name",
+      "type": "text",
+      "rule": "person-name",
+      "category": "identity",
+      "expected": "full-name"
+    },
+    {
+      "entity": "invoices",
+      "field": "vat_number",
+      "type": "varchar(32)",
+      "rule": "government-id",
+      "category": "government_id",
+      "expected": "token"
+    },
+    {
+      "entity": "invoices",
+      "field": "amount_cents",
+      "type": "integer",
+      "rule": null,
+      "expected": "keep"
+    },
+    {
+      "entity": "support_tickets",
+      "field": "body",
+      "type": "text",
+      "rule": null,
+      "expected": "token"
+    },
+    {
+      "entity": "support_tickets",
+      "field": "requester_id",
+      "type": "integer",
+      "rule": null,
+      "expected": "keep"
+    },
+    {
+      "entity": "devices",
+      "field": "device_id",
+      "type": "uuid",
+      "rule": "online-identifier",
+      "category": "online_identifier",
+      "expected": "uuid"
+    },
+    {
+      "entity": "devices",
+      "field": "push_token",
+      "type": "text",
+      "rule": "online-identifier",
+      "category": "online_identifier",
+      "expected": "token"
+    },
+    {
+      "entity": "devices",
+      "field": "last_seen_ip",
+      "type": "inet",
+      "rule": "online-identifier",
+      "category": "online_identifier",
+      "expected": "ip"
+    },
+    {
+      "entity": "profiles",
+      "field": "username",
+      "type": "text",
+      "rule": "username",
+      "category": "identity",
+      "expected": "username"
+    },
+    {
+      "entity": "profiles",
+      "field": "preferences",
+      "type": "jsonb",
+      "rule": null,
+      "expected": "keep"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@stonekeep/ai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.8.0",
+  "description": "Stonekeep AI setup assistant with a pre-send privacy guardrail.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "eval"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^1.6.0",
+    "yaml": "^2.9.1",
+    "zod": "^3.25.76",
+    "@stonekeep/core": "0.8.0"
+  },
+  "keywords": [
+    "gdpr",
+    "rodo",
+    "privacy",
+    "compliance",
+    "poland"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "eval": "node dist/eval-cli.js"
+  }
 }