@silo-ai/silo 0.0.0 → 0.1.0

package/dist/report-viewer.css

@@ -0,0 +1,428 @@
+:root {
+  color-scheme: light dark;
+  --background: #f4f1ea;
+  --surface: rgba(255, 255, 255, 0.88);
+  --surface-strong: #ffffff;
+  --ink: #18201d;
+  --muted: #68716d;
+  --line: rgba(24, 32, 29, 0.13);
+  --accent: #1d6b52;
+  --accent-soft: #dcece5;
+  --danger: #a44037;
+  --shadow: 0 24px 70px rgba(51, 45, 32, 0.1);
+  font-family:
+    Inter,
+    ui-sans-serif,
+    -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    sans-serif;
+  font-synthesis: none;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  min-height: 100vh;
+  color: var(--ink);
+  background:
+    radial-gradient(circle at 8% 0%, rgba(29, 107, 82, 0.1), transparent 30rem),
+    linear-gradient(180deg, #f8f6f1, var(--background));
+}
+
+.site-header {
+  position: sticky;
+  z-index: 10;
+  top: 0;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 4.25rem;
+  padding: 0.7rem max(1.25rem, calc((100vw - 90rem) / 2));
+  border-bottom: 1px solid var(--line);
+  background: rgba(248, 246, 241, 0.82);
+  backdrop-filter: blur(18px);
+}
+
+.brand {
+  display: inline-flex;
+  gap: 0.7rem;
+  align-items: center;
+  color: inherit;
+  font-size: 0.82rem;
+  font-weight: 750;
+  letter-spacing: 0.08em;
+  text-decoration: none;
+  text-transform: uppercase;
+}
+
+.brand-mark {
+  display: grid;
+  width: 2rem;
+  height: 2rem;
+  place-items: center;
+  border-radius: 0.6rem;
+  color: #fff;
+  background: var(--accent);
+  box-shadow: 0 5px 16px rgba(29, 107, 82, 0.24);
+}
+
+.refresh-state {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+  color: var(--muted);
+  font-size: 0.82rem;
+  font-weight: 650;
+}
+
+.status-dot {
+  width: 0.55rem;
+  height: 0.55rem;
+  border-radius: 999px;
+  background: var(--accent);
+  box-shadow: 0 0 0 0.25rem var(--accent-soft);
+}
+
+[data-refresh-state='refreshing'] .status-dot {
+  animation: pulse 1.2s ease-in-out infinite;
+}
+
+[data-refresh-state='stale'] .status-dot {
+  background: var(--danger);
+  box-shadow: 0 0 0 0.25rem color-mix(in srgb, var(--danger) 14%, transparent);
+}
+
+.page-shell {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 19rem;
+  gap: 1.5rem;
+  width: min(90rem, 100%);
+  margin: 0 auto;
+  padding: clamp(1.25rem, 3vw, 3rem);
+}
+
+.report-card,
+.metadata-card,
+.query-panel {
+  border: 1px solid var(--line);
+  background: var(--surface);
+  box-shadow: var(--shadow);
+}
+
+.report-card {
+  min-width: 0;
+  padding: clamp(1.5rem, 4vw, 4.5rem);
+  border-radius: 1.25rem;
+}
+
+.report-sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  align-self: start;
+  position: sticky;
+  top: 5.75rem;
+}
+
+.metadata-card,
+.query-panel {
+  overflow: hidden;
+  border-radius: 1rem;
+}
+
+.metadata-card {
+  padding: 1.25rem;
+}
+
+.eyebrow {
+  margin: 0 0 0.35rem;
+  color: var(--accent);
+  font-size: 0.72rem;
+  font-weight: 800;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+
+.metadata-card h2 {
+  margin: 0;
+  font-family: Georgia, 'Times New Roman', serif;
+  font-size: 1.25rem;
+  line-height: 1.2;
+}
+
+.metadata-card dl {
+  display: grid;
+  gap: 0.8rem;
+  margin: 1.25rem 0 0;
+}
+
+.metadata-card dl div {
+  display: grid;
+  gap: 0.2rem;
+}
+
+.metadata-card dt {
+  color: var(--muted);
+  font-size: 0.72rem;
+  font-weight: 700;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+}
+
+.metadata-card dd {
+  margin: 0;
+  font-size: 0.86rem;
+}
+
+.refresh-error {
+  margin: 1rem 0 0;
+  padding: 0.75rem;
+  border-radius: 0.65rem;
+  color: var(--danger);
+  background: color-mix(in srgb, var(--danger) 8%, transparent);
+  font-size: 0.82rem;
+  line-height: 1.45;
+}
+
+.query-panel summary {
+  padding: 1rem 1.15rem;
+  cursor: pointer;
+  font-size: 0.85rem;
+  font-weight: 720;
+}
+
+.query-panel summary:focus-visible,
+a:focus-visible {
+  outline: 3px solid color-mix(in srgb, var(--accent) 40%, transparent);
+  outline-offset: 3px;
+}
+
+.query-list {
+  display: grid;
+  gap: 1rem;
+  padding: 0 1rem 1rem;
+}
+
+.query-list h3 {
+  margin: 0 0 0.45rem;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.78rem;
+}
+
+.query-list pre {
+  max-height: 18rem;
+  margin: 0;
+  padding: 0.8rem;
+  overflow: auto;
+  border: 1px solid var(--line);
+  border-radius: 0.65rem;
+  background: color-mix(in srgb, var(--surface-strong) 72%, var(--background));
+  font-size: 0.72rem;
+  line-height: 1.5;
+  white-space: pre-wrap;
+}
+
+.report-markdown {
+  font-family: Georgia, 'Times New Roman', serif;
+  font-size: clamp(1rem, 0.96rem + 0.18vw, 1.12rem);
+  line-height: 1.75;
+}
+
+.report-markdown > :first-child {
+  margin-top: 0;
+}
+
+.report-markdown > :last-child {
+  margin-bottom: 0;
+}
+
+.report-markdown h1,
+.report-markdown h2,
+.report-markdown h3 {
+  color: var(--ink);
+  line-height: 1.14;
+  text-wrap: balance;
+}
+
+.report-markdown h1 {
+  max-width: 18ch;
+  margin: 0 0 2rem;
+  font-size: clamp(2.35rem, 6vw, 5.3rem);
+  font-weight: 500;
+  letter-spacing: -0.045em;
+}
+
+.report-markdown h2 {
+  margin: 2.8rem 0 1rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--line);
+  font-size: clamp(1.55rem, 3vw, 2.15rem);
+  font-weight: 560;
+  letter-spacing: -0.025em;
+}
+
+.report-markdown h3 {
+  margin-top: 2rem;
+  font-size: 1.25rem;
+}
+
+.report-markdown a {
+  color: var(--accent);
+  text-decoration-thickness: 0.08em;
+  text-underline-offset: 0.14em;
+}
+
+.report-markdown code {
+  border-radius: 0.28rem;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.84em;
+  background: var(--accent-soft);
+}
+
+.report-markdown :not(pre) > code {
+  padding: 0.12em 0.35em;
+}
+
+.report-markdown pre {
+  padding: 1rem 1.1rem;
+  overflow: auto;
+  border: 1px solid var(--line);
+  border-radius: 0.8rem;
+  background: #18201d;
+  color: #edf3ef;
+  line-height: 1.55;
+}
+
+.report-markdown pre code {
+  background: transparent;
+}
+
+.report-markdown blockquote {
+  margin: 1.5rem 0;
+  padding: 0.15rem 0 0.15rem 1.2rem;
+  border-left: 3px solid var(--accent);
+  color: var(--muted);
+}
+
+.report-markdown table {
+  display: block;
+  width: 100%;
+  margin: 1.25rem 0 2rem;
+  overflow-x: auto;
+  border-collapse: collapse;
+  font-family:
+    ui-sans-serif,
+    -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    sans-serif;
+  font-size: 0.88rem;
+  line-height: 1.45;
+}
+
+.report-markdown th,
+.report-markdown td {
+  padding: 0.75rem 0.85rem;
+  border-bottom: 1px solid var(--line);
+  text-align: left;
+  vertical-align: top;
+}
+
+.report-markdown th {
+  color: var(--muted);
+  font-size: 0.72rem;
+  font-weight: 800;
+  letter-spacing: 0.055em;
+  text-transform: uppercase;
+}
+
+.report-markdown tbody tr:hover {
+  background: color-mix(in srgb, var(--accent) 5%, transparent);
+}
+
+@keyframes pulse {
+  50% {
+    opacity: 0.4;
+    transform: scale(0.82);
+  }
+}
+
+@media (max-width: 900px) {
+  .page-shell {
+    grid-template-columns: 1fr;
+  }
+
+  .report-sidebar {
+    position: static;
+    grid-row: 1;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  }
+}
+
+@media (max-width: 620px) {
+  .site-header {
+    padding-inline: 1rem;
+  }
+
+  .page-shell {
+    padding: 0.75rem;
+  }
+
+  .report-sidebar {
+    grid-template-columns: 1fr;
+  }
+
+  .report-card {
+    padding: 1.25rem;
+    border-radius: 0.9rem;
+  }
+
+  .report-markdown h1 {
+    font-size: 2.4rem;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    scroll-behavior: auto !important;
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+  }
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #111714;
+    --surface: rgba(27, 35, 31, 0.9);
+    --surface-strong: #202a25;
+    --ink: #edf3ef;
+    --muted: #aab7b0;
+    --line: rgba(237, 243, 239, 0.12);
+    --accent: #75c6a6;
+    --accent-soft: #203d32;
+    --danger: #f19a90;
+    --shadow: 0 24px 70px rgba(0, 0, 0, 0.24);
+  }
+
+  body {
+    background:
+      radial-gradient(circle at 8% 0%, rgba(117, 198, 166, 0.08), transparent 30rem),
+      var(--background);
+  }
+
+  .site-header {
+    background: rgba(17, 23, 20, 0.84);
+  }
+
+  .brand-mark {
+    color: #102019;
+  }
+}

package/package.json

@@ -1,13 +1,54 @@
 {
   "name": "@silo-ai/silo",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
+  "version": "0.1.0",
+  "license": "MIT OR Apache-2.0",
+  "author": "Alec Larson",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/silo-ai/silo.git"
+  },
+  "bin": {
+    "silo": "./dist/bin.mjs"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "templates"
+  ],
+  "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "dev": "tsdown --sourcemap --watch",
+    "build": "tsdown",
+    "docs:dev": "lildocs dev ./docs",
+    "docs:build": "lildocs build ./docs --out ./dist/docs",
+    "format": "oxfmt .",
+    "lint": "oxlint src",
+    "typecheck": "tsc --noEmit && tsc -p test --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build",
+    "sync-agent-rules": "curl -fsSL https://gist.githubusercontent.com/aleclarson/4c80686b1c3e204a01cdbe82f8e2c084/raw/AGENTS.md -o AGENTS.md && git add AGENTS.md && git commit -m 'chore: sync agent rules'"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1079.0",
+    "cmd-ts": "^0.15.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "lildocs": "^0.1.20",
+    "oxfmt": "^0.57.0",
+    "oxlint": "^1.72.0",
+    "tsdown": "^0.22.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=24.10.0"
   },
-  "keywords": [],
-  "author": "",
-  "license": "All rights reserved",
-  "type": "commonjs"
+  "packageManager": "pnpm@11.5.1"
 }

package/skills/silo/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: silo
+description: Design, operate, explicitly synchronize, and publish refreshable Markdown reports from strictly typed, Git-scoped SQLite databases with the Silo CLI. Use when an agent needs durable structured state for a repository, needs to define or inspect Silo tables, choose semantic types or policies, safely mutate rows, query a workspace's Silo database, exchange it through a configured S3-compatible remote, or publish a saved-query report for human viewers.
+---
+
+# Silo
+
+Treat Silo as durable repository state, not scratch storage. Resolve the current Git workspace first with `silo status`; never assume two checkouts with different normalized origins share a database.
+
+## Common operations
+
+Resolve and inspect before working with unfamiliar data:
+
+```sh
+silo status
+silo schema show
+silo table show issues
+```
+
+Add one row, list rows, or retrieve a known key:
+
+```sh
+printf '%s\n' '{"title":"Document release process"}' | silo row add issues
+silo row list issues --limit 20
+silo row get issues 550e8400-e29b-41d4-a716-446655440000
+```
+
+Row add and upsert output the complete persisted rows, including generated identities, defaults, timestamps, and revisions. Use the exact table and column names returned by inspection. Read [the row request schema](schemas/row-write.schema.json) before constructing unfamiliar or bulk row input.
+
+## Task guides
+
+Read only the guide needed for workflows with additional design or safety considerations:
+
+- [Create a table](tasks/create-table.md) — define the first table or add another durable entity.
+- [Update with optimistic revision](tasks/update-with-revision.md) — avoid overwriting a concurrent agent's changes.
+- [Perform an idempotent upsert](tasks/upsert-rows.md) — repeat a write safely through a declared natural key.
+- [Query with SQL](tasks/query-with-sql.md) — join, filter, aggregate, or inspect data through a read-only query.
+- [Make an additive schema change](tasks/alter-table.md) — add a nullable/defaulted column or index.
+- [Synchronize a database](tasks/synchronize.md) — pull, push, inspect status, and recover from conflicts safely.
+- [Create a refreshable report](tasks/create-report.md) — combine durable Markdown framing with current saved-query results.
+
+## Design schemas
+
+- Start from access patterns and durable entities. Keep each table comment explicit about what one row represents, when an agent should read or write it, and what it must not contain.
+- Follow every attributed agent-instruction block shown by `silo schema show`; template imports copy these schema-wide workflow rules into the local authoritative schema.
+- Give every column a non-empty comment describing domain meaning, units, canonical form, and null meaning when non-obvious.
+- Prefer a semantic type over a bare storage type when its validation contract matches the domain. Do not use semantic names as decoration.
+- Supply native objects, arrays, strings, numbers, or booleans to `text/json`; Silo stores canonical compact JSON. JSON `null` means SQL `NULL`.
+- Use `any` only for SQLite scalar values. It accepts strings, finite numbers, booleans, and `null`, but not objects or arrays; booleans are stored as `0` or `1`.
+- Use `text/datetime` for instants and `text/date` for calendar dates. Store exact money as minor-unit integers or `text/decimal` with explicit precision and scale; do not use `REAL` for exact amounts.
+- Expect literal defaults to follow the same semantic validation and canonicalization rules as row input.
+- Declare stable primary or natural keys. Add indexes only for demonstrated lookup, join, ordering, or uniqueness needs.
+- Put durable invariants in keys, checks, foreign keys, unique constraints, or policies. Comments guide agents but do not enforce behavior.
+- Prefer small additive schema changes. Initial Silo alterations cannot rebuild tables or change existing types, keys, checks, generated columns, or policies.
+
+Read [table-create.schema.json](schemas/table-create.schema.json) before constructing a table request and [table-alter.schema.json](schemas/table-alter.schema.json) before altering one. Use generated `silo <group> <command> --help` output for syntax and examples; do not infer flags from this skill.
+
+## Select policies
+
+- Use `generated_identity` only when the domain lacks a stable natural identifier. UUID and ULID values are generated by the CLI; integer identities use SQLite rowid behavior.
+- Use `timestamps` for operational creation/update instants. Preserve domain event time in separate columns.
+- Use `optimistic_revision` when agents may race to update the same row. Read the row, retain its revision, and pass `_expected_revision` on update; on conflict, reread and reconcile.
+- Use `immutable_columns` for facts fixed after insertion, `immutable_rows` when a row can never change or be deleted, and `append_only` for log-like tables. These are integrity controls, not tamper-proof auditing.
+- Use `natural_key_upsert` only for truly idempotent writes with an unambiguous conflict key and deliberately limited update columns.
+
+Inspect `silo table show` to distinguish `constraint`, `trigger`, and `cli` enforcement. External SQLite clients can bypass CLI-only canonicalization and generation.
+
+## Mutate safely
+
+Read [row-write.schema.json](schemas/row-write.schema.json) for row request shape.
+
+1. Inspect the schema or table before writing unfamiliar data.
+2. Canonicalize meaning at the source; let Silo validate and normalize representation.
+3. Prefer one atomic array write for rows that must succeed together.
+4. Use upsert only when the table declares it. Otherwise choose insert or an explicit read/update flow.
+5. Treat constraint failures as domain feedback. Do not weaken the schema merely to accept one value.
+6. Use explicit delete commands only after verifying the key and downstream foreign-key behavior.
+
+## Query and interpret
+
+- Prefer row commands for key-based operations and `silo sql` for joins, aggregates, CTEs, window functions, and JSON reads.
+- Add `ORDER BY` whenever result order matters; raw SQL follows SQLite ordering semantics.
+- Remember that exact decimals and semantic versions stored as text do not have numerically meaningful native lexical ordering.
+- Treat Markdown output as presentation. Success and failure are determined by exit status.
+- Use `schema export` for portable logical metadata and `schema ddl` only to diagnose compiled artifacts. Never reconstruct semantic meaning from raw DDL.
+
+## Publish reports
+
+- Use reports for stable human-facing briefs, status summaries, and data-quality views that benefit from deterministic refresh.
+- Put changing facts in named query slots and durable framing in ordinary Markdown. Refresh reruns SQL; it does not invoke an agent or rewrite prose.
+- Read [report-put.schema.json](schemas/report-put.schema.json) before constructing a report definition, and follow [Create a refreshable report](tasks/create-report.md) for the complete workflow.
+- Treat a saved report as part of the Silo that contains its source data. Do not duplicate report output into repository files as a second source of truth.
+
+## Avoid common mistakes
+
+- Do not create placeholder comments, duplicate JSON output modes, raw SQL mutations, hidden soft deletion, or audit claims.
+- Do not edit `_silo_` objects or metadata directly.
+- Do not move active databases into network or cloud-synchronized storage.
+- Do not assume synchronization is automatic. Pull before shared work and push only after reviewing pending local state.
+- Do not resolve a changeset conflict by editing `_silo_` metadata or by retrying blindly. Use the transaction-aware discard and reconciliation workflow.
+- Do not assume changing `origin` migrates data; it intentionally selects a different identity and database.

package/skills/silo/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Silo'
+  short_description: 'Design and operate Git-scoped Silo databases'
+  default_prompt: 'Use $silo to design or operate the typed SQLite database for this Git workspace.'

package/skills/silo/schemas/report-put.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/silo-ai/silo/schemas/report-put.schema.json",
+  "title": "Silo report definition",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["slug", "title", "markdown", "queries"],
+  "properties": {
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "markdown": {
+      "type": "string",
+      "minLength": 1
+    },
+    "queries": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "sql"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_-]*$"
+          },
+          "sql": {
+            "type": "string",
+            "minLength": 1
+          },
+          "empty_markdown": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}

package/skills/silo/schemas/row-write.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/silo-ai/silo/skills/silo/schemas/row-write.schema.json",
+  "title": "Silo row write request",
+  "description": "A single row or an atomic batch. Field names are constrained by the target logical schema.",
+  "oneOf": [{ "type": "object" }, { "type": "array", "minItems": 1, "items": { "type": "object" } }]
+}

package/skills/silo/schemas/table-alter.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/silo-ai/silo/skills/silo/schemas/table-alter.schema.json",
+  "title": "Silo additive table alteration request",
+  "type": "object",
+  "additionalProperties": false,
+  "minProperties": 1,
+  "properties": {
+    "add_columns": {
+      "type": "array",
+      "items": { "$ref": "table-create.schema.json#/$defs/column" }
+    },
+    "add_indexes": { "type": "array", "items": { "$ref": "table-create.schema.json#/$defs/index" } }
+  }
+}