@silo-ai/silo 0.0.0 → 0.1.0

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

@@ -0,0 +1,188 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/silo-ai/silo/skills/silo/schemas/table-create.schema.json",
+  "title": "Silo table creation request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "comment", "columns"],
+  "properties": {
+    "name": { "$ref": "#/$defs/identifier" },
+    "comment": { "type": "string", "minLength": 1 },
+    "columns": { "type": "array", "items": { "$ref": "#/$defs/column" } },
+    "primary_key": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/identifier" } },
+    "foreign_keys": { "type": "array", "items": { "$ref": "#/$defs/foreignKey" } },
+    "unique_constraints": { "type": "array", "items": { "$ref": "#/$defs/unique" } },
+    "indexes": { "type": "array", "items": { "$ref": "#/$defs/index" } },
+    "checks": { "type": "array", "items": { "$ref": "#/$defs/check" } },
+    "policies": { "type": "array", "items": { "$ref": "#/$defs/policy" } },
+    "strict": { "type": "boolean", "default": true },
+    "without_rowid": { "type": "boolean", "default": false }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+      "not": { "pattern": "^_[sS][iI][lL][oO]_" }
+    },
+    "column": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "type", "comment"],
+      "properties": {
+        "name": { "$ref": "#/$defs/identifier" },
+        "type": { "type": "string", "minLength": 1 },
+        "type_options": { "type": "object" },
+        "nullable": { "type": "boolean", "default": true },
+        "comment": { "type": "string", "minLength": 1 },
+        "collate": { "$ref": "#/$defs/identifier" },
+        "default": {
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "maxProperties": 1,
+          "properties": {
+            "literal": {},
+            "expression": { "type": "string", "minLength": 1 }
+          }
+        },
+        "generated": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["expression"],
+          "properties": {
+            "expression": { "type": "string", "minLength": 1 },
+            "storage": { "enum": ["VIRTUAL", "STORED"] }
+          }
+        }
+      }
+    },
+    "foreignKey": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["columns", "references"],
+      "properties": {
+        "columns": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/identifier" } },
+        "references": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["table", "columns"],
+          "properties": {
+            "table": { "$ref": "#/$defs/identifier" },
+            "columns": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/identifier" } }
+          }
+        },
+        "on_update": { "$ref": "#/$defs/action" },
+        "on_delete": { "$ref": "#/$defs/action" },
+        "deferrable": { "type": "boolean" },
+        "initially_deferred": { "type": "boolean" }
+      }
+    },
+    "action": { "enum": ["NO ACTION", "RESTRICT", "SET NULL", "SET DEFAULT", "CASCADE"] },
+    "unique": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["columns"],
+      "properties": {
+        "name": { "$ref": "#/$defs/identifier" },
+        "columns": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/identifier" } }
+      }
+    },
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["expression"],
+      "properties": {
+        "name": { "$ref": "#/$defs/identifier" },
+        "expression": { "type": "string", "minLength": 1 },
+        "comment": { "type": "string" }
+      }
+    },
+    "indexPart": {
+      "type": "object",
+      "additionalProperties": false,
+      "oneOf": [{ "required": ["column"] }, { "required": ["expression"] }],
+      "properties": {
+        "column": { "$ref": "#/$defs/identifier" },
+        "expression": { "type": "string", "minLength": 1 },
+        "direction": { "enum": ["ASC", "DESC"] },
+        "collate": { "$ref": "#/$defs/identifier" }
+      }
+    },
+    "index": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["columns"],
+      "properties": {
+        "name": { "$ref": "#/$defs/identifier" },
+        "columns": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/indexPart" } },
+        "unique": { "type": "boolean" },
+        "where": { "type": "string", "minLength": 1 },
+        "comment": { "type": "string" }
+      }
+    },
+    "policy": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "column", "strategy"],
+          "properties": {
+            "type": { "const": "generated_identity" },
+            "column": { "$ref": "#/$defs/identifier" },
+            "strategy": { "enum": ["integer", "uuid", "ulid"] }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type"],
+          "anyOf": [{ "required": ["created_column"] }, { "required": ["updated_column"] }],
+          "properties": {
+            "type": { "const": "timestamps" },
+            "created_column": { "$ref": "#/$defs/identifier" },
+            "updated_column": { "$ref": "#/$defs/identifier" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "column"],
+          "properties": {
+            "type": { "const": "optimistic_revision" },
+            "column": { "$ref": "#/$defs/identifier" },
+            "initial": { "type": "integer" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type"],
+          "properties": { "type": { "enum": ["immutable_rows", "append_only"] } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "columns"],
+          "properties": {
+            "type": { "const": "immutable_columns" },
+            "columns": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/identifier" } }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "columns"],
+          "properties": {
+            "type": { "const": "natural_key_upsert" },
+            "columns": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "$ref": "#/$defs/identifier" }
+            },
+            "update_columns": { "type": "array", "items": { "$ref": "#/$defs/identifier" } }
+          }
+        }
+      ]
+    }
+  }
+}

package/skills/silo/tasks/alter-table.md

@@ -0,0 +1,25 @@
+# Make an additive schema change
+
+> Extend an existing table without invoking an unsupported or destructive table rebuild.
+
+Inspect [the alteration request schema](../schemas/table-alter.schema.json), then add a nullable column and an index:
+
+```sh
+silo table alter issues <<'JSON'
+{
+  "add_columns": [
+    {
+      "name": "owner",
+      "type": "text",
+      "nullable": true,
+      "comment": "Agent or team currently responsible for the issue; NULL means unassigned."
+    }
+  ],
+  "add_indexes": [
+    { "columns": [{ "column": "owner" }] }
+  ]
+}
+JSON
+```
+
+Verify the new logical definition with `silo table show issues`. Initial Silo alterations do not rename or drop columns, tighten nullability, change keys or types, or modify policies.

package/skills/silo/tasks/create-report.md

@@ -0,0 +1,43 @@
+# Create a refreshable report
+
+Use a report when a human should revisit a stable explanation whose factual tables come from current Silo data. Keep changing facts inside query slots; refreshing does not ask an agent to rewrite ordinary Markdown.
+
+Read [the report request schema](../schemas/report-put.schema.json), then define the report and every referenced query:
+
+```json
+{
+  "slug": "execution-brief",
+  "title": "Project execution brief",
+  "markdown": "# Project execution brief\n\n## Work by status\n\n{{silo-query:work_by_status}}",
+  "queries": [
+    {
+      "name": "work_by_status",
+      "sql": "SELECT status, count(*) AS tasks FROM tasks GROUP BY status ORDER BY tasks DESC",
+      "empty_markdown": "_No tasks._"
+    }
+  ]
+}
+```
+
+Save and perform the initial refresh atomically:
+
+```sh
+silo report put --file execution-brief.json
+```
+
+Use `ORDER BY` whenever presentation order matters. Each query must be one read-only statement, every saved query must have a matching `{{silo-query:name}}` slot, and every slot must name a saved query. Failed replacements leave an existing valid report unchanged.
+
+Inspect or refresh the saved report:
+
+```sh
+silo report show execution-brief
+silo report refresh execution-brief
+```
+
+Open the packaged human viewer when the report is ready to hand off:
+
+```sh
+silo report open execution-brief
+```
+
+The foreground command serves only on loopback and runs until interrupted. The page shows the last successful rendering immediately and refreshes in the background after opening or regaining focus; a refresh error leaves that rendering visible.

package/skills/silo/tasks/create-table.md

@@ -0,0 +1,36 @@
+# Create a table
+
+> Define a durable entity with comments, semantic types, keys, and policies before writing rows.
+
+Inspect [the table request schema](../schemas/table-create.schema.json), then create an `issues` table:
+
+```sh
+silo table create <<'JSON'
+{
+  "name": "issues",
+  "comment": "One actionable repository issue; read before planning work.",
+  "columns": [
+    { "name": "id", "type": "text/uuid", "nullable": false, "comment": "Stable generated issue identifier." },
+    { "name": "title", "type": "text", "nullable": false, "comment": "Short actionable summary." },
+    { "name": "context", "type": "text/json", "nullable": false, "comment": "Structured labels and routing context." }
+  ],
+  "primary_key": ["id"],
+  "policies": [
+    { "type": "generated_identity", "column": "id", "strategy": "uuid" }
+  ]
+}
+JSON
+```
+
+The first schema mutation also creates the workspace database. Add a row with native JSON rather than a serialized JSON string:
+
+```sh
+silo row add issues <<'JSON'
+{
+  "title": "Document release process",
+  "context": { "labels": ["docs", "release"] }
+}
+JSON
+```
+
+The output includes the generated UUID and canonical persisted values. Verify the logical contract with `silo table show issues`.

package/skills/silo/tasks/query-with-sql.md

@@ -0,0 +1,27 @@
+# Query with SQL
+
+> Use SQLite-native reads for joins, aggregates, CTEs, windows, and JSON operations without enabling mutation.
+
+Add explicit ordering whenever result order matters:
+
+```sh
+silo sql '
+  SELECT status, count(*) AS issue_count
+  FROM issues
+  GROUP BY status
+  ORDER BY status
+'
+```
+
+For longer queries, send SQL through stdin:
+
+```sh
+silo sql <<'SQL'
+WITH recent AS (
+  SELECT * FROM issues ORDER BY created_at DESC LIMIT 10
+)
+SELECT id, title FROM recent ORDER BY created_at DESC;
+SQL
+```
+
+The connection is read-only. Use row commands for mutations and remember that exact decimals and semantic versions do not have numerically meaningful lexical ordering.

package/skills/silo/tasks/synchronize.md

@@ -0,0 +1,34 @@
+# Synchronize a database
+
+> Exchange local Silo transactions through an already authorized S3-compatible remote without silently choosing a conflict winner.
+
+Before initialization, verify Litestream 0.5.12 or newer is installed and that the standard AWS credential environment is available to both Silo and Litestream. Keep the active database on local storage.
+
+Initialize once, then inspect the result:
+
+```sh
+silo sync init s3://my-bucket/silo/project
+silo sync status
+```
+
+An existing local database with an empty remote becomes `ahead`; push it to establish remote `HEAD`. An absent local database restores an existing remote. Do not attempt to combine an existing unconfigured local database with an existing remote.
+
+For normal shared work:
+
+```sh
+silo pull
+# Inspect and mutate through ordinary Silo commands.
+silo push
+```
+
+Treat `ahead`, `behind`, and `diverged` as synchronization state, not errors to bypass. Pull rebases non-conflicting pending row transactions. If status is `conflicted`, preserve any values needed from the identified operation, then discard only that transaction and issue a deliberate reconciled mutation:
+
+```sh
+silo sync discard <transaction-id>
+```
+
+Discard rebuilds from remote and replays the remaining pending transactions; it permanently removes the selected transaction's effects. Never delete an outbox row directly.
+
+Schema commands require `clean` status and no pending data transaction. Pull first, make one schema mutation, and push it before further work. Concurrent schema changes do not merge; discard the losing schema transaction, adopt the remote winner, and reapply a compatible change deliberately.
+
+Synchronization is explicit. There is no background replication, Git-style history, automatic conflict winner, or automatic remote generation cleanup.

package/skills/silo/tasks/update-with-revision.md

@@ -0,0 +1,22 @@
+# Update with optimistic revision
+
+> Apply a change only when the row still has the revision previously read by the agent.
+
+First read the current row and retain its `revision` value:
+
+```sh
+silo row get issues 550e8400-e29b-41d4-a716-446655440000
+```
+
+If the row reports revision `3`, submit the expected revision with the changed fields:
+
+```sh
+silo row update issues 550e8400-e29b-41d4-a716-446655440000 <<'JSON'
+{
+  "title": "Document and automate release process",
+  "_expected_revision": 3
+}
+JSON
+```
+
+On a revision conflict, reread the row and reconcile the other writer's changes. Never retry blindly with a newer revision.

package/skills/silo/tasks/upsert-rows.md

@@ -0,0 +1,18 @@
+# Perform an idempotent upsert
+
+> Repeat a write safely when the table declares a natural conflict key and allowed update fields.
+
+Confirm that `silo table show dependencies` lists a `natural_key_upsert` policy. Then upsert through that declared key:
+
+```sh
+silo row upsert dependencies <<'JSON'
+{
+  "package": "better-sqlite3",
+  "latest_version": "12.4.1"
+}
+JSON
+```
+
+Running the same command again updates only the fields allowed by the policy. If the table has no such policy, use an explicit read followed by insert or update instead.
+
+When no update fields are needed, supply only the complete natural key. Silo performs a no-op and returns the existing persisted row instead of issuing an empty update.