@fluxyr/quill-core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared types for the Quill engine.
+ *
+ * Quill treats a web app as an ordered stack of micro-prompts (the durable
+ * asset) plus a resolved state (the lockfile). Code is a derived artifact,
+ * generated/evolved by opencode and verified by a stack adapter.
+ */
+export type PromptKind = "core" | "feature";
+/** A single micro-prompt: natural-language spec + metadata. */
+export interface PromptDoc {
+    /** Stable id, e.g. "0002-add-projects". */
+    id: string;
+    kind: PromptKind;
+    /** Ids this prompt depends on (informational; ordering is by `order`). */
+    dependsOn: string[];
+    /** Numeric prefix used to order feature prompts like migrations. */
+    order: number;
+    /** The natural-language specification. */
+    body: string;
+    /** Absolute path to the source markdown, when read from disk. */
+    filePath?: string;
+}
+/** A non-generated file copied verbatim into the generated app on init. */
+export interface FileTemplate {
+    /** Path relative to the generated app root. */
+    path: string;
+    content: string;
+}
+/** Result of a stack adapter's verify() — feeds the repair loop. */
+export interface VerifyResult {
+    ok: boolean;
+    /** One-line summary for logs. */
+    summary: string;
+    /** Detailed feedback (compiler/test output) fed back to opencode on failure. */
+    feedback: string;
+}
+/** Context handed to a stack adapter when composing the system prompt. */
+export interface StackContext {
+    corePrompts: PromptDoc[];
+    /** Absolute path to the generated app root. */
+    generatedDir: string;
+}
+/**
+ * A stack adapter encodes one target technology (e.g. Python/Flask). It does NOT
+ * own the core conventions (those are shared, in @fluxyr/quill-core); it contributes the
+ * framework binding (via buildSystemPrompt), the verbatim scaffold, and verify().
+ */
+export interface StackAdapter {
+    name: string;
+    /** Files copied verbatim into the generated app (load-bearing, byte-stable). */
+    scaffoldTemplates(): FileTemplate[];
+    /**
+     * Compose the system prompt: the shared core conventions (ctx.corePrompts,
+     * passed in by the engine) followed by this stack's framework binding.
+     */
+    buildSystemPrompt(ctx: StackContext): string;
+    /** Compile/lint/test the generated app; returns feedback for the repair loop. */
+    verify(generatedDir: string): Promise<VerifyResult>;
+}
+/** LLM generation settings. Quill calls the provider's API directly. */
+export interface LlmConfig {
+    /** Provider whose API we call. OpenRouter exposes every model behind one key. */
+    provider: "openrouter";
+    /** API base URL (default https://openrouter.ai/api/v1). */
+    baseUrl?: string;
+    /** Max repair passes after the initial generation (default 2). */
+    maxRepairPasses: number;
+    /** Sampling temperature (default 0 for reproducibility). */
+    temperature: number;
+    /** Run one self-review pass before verification (the article's doctrine). */
+    selfReview: boolean;
+}
+/** Project configuration persisted as quill.config.json. */
+export interface QuillConfig {
+    /** Stack adapter name, e.g. "flask". */
+    stack: string;
+    /** Model slug as "provider/model" (OpenRouter), e.g. "minimax/minimax-m3". */
+    model: string;
+    paths: {
+        /** Prompts root, relative to project. */
+        prompts: string;
+        /** Generated app root, relative to project. */
+        generated: string;
+    };
+    llm: LlmConfig;
+}
+/** One applied feature prompt in the ledger. */
+export interface AppliedEntry {
+    id: string;
+    promptHash: string;
+    codeHash: string;
+    model: string;
+    repairPasses: number;
+    appliedAt: string;
+}
+/** A named checkpoint: snapshot + reproducibility verdict. */
+export interface CheckpointEntry {
+    name: string;
+    /** Last applied prompt id at checkpoint time (the "head"). */
+    head: string | null;
+    /** Snapshot dir relative to project, under .quill/checkpoints/. */
+    snapshotDir: string;
+    codeHash: string;
+    verified: boolean;
+    verifiedAt: string;
+}
+/** The resolved state: quill.lock.json. */
+export interface Lockfile {
+    version: number;
+    stack: string;
+    model: string;
+    applied: AppliedEntry[];
+    checkpoints: CheckpointEntry[];
+}
+/** A chat message in the generation conversation. */
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/** One file operation emitted by the model. */
+export interface FileOp {
+    path: string;
+    action: "write" | "delete";
+    content?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Shared types for the Quill engine.
+ *
+ * Quill treats a web app as an ordered stack of micro-prompts (the durable
+ * asset) plus a resolved state (the lockfile). Code is a derived artifact,
+ * generated/evolved by opencode and verified by a stack adapter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@fluxyr/quill-core",
+  "version": "0.1.0",
+  "description": "Quill engine: shared conventions, micro-prompt ledger, OpenRouter engine, repair loop.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "prompts"
+  ],
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  },
+  "license": "MIT",
+  "author": "Fluxyr",
+  "homepage": "https://github.com/fluxyr-app/quill#readme",
+  "bugs": {
+    "url": "https://github.com/fluxyr-app/quill/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fluxyr-app/quill.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "quill",
+    "code-generation",
+    "llm",
+    "micro-prompts",
+    "openrouter",
+    "scaffolding"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/prompts/000-uuid.md

@@ -0,0 +1,27 @@
+---
+id: 000-uuid
+kind: core
+depends_on: []
+---
+# Identifiers — short IDs
+
+Every resource is identified by a **UUID**. Internally — storage, foreign keys,
+comparisons — the full UUID is used. Externally — everywhere an id crosses the
+boundary to a client (URL paths, request bodies, response payloads) — the id is
+represented as a compact **short ID**.
+
+Short ID semantics:
+- The short ID is a **Base-62** encoding of the 128-bit UUID using the alphabet
+  `0-9`, then `A-Z`, then `a-z` (digit value 0 = `0`, … 61 = `z`),
+  most-significant digit first, left-padded to a fixed length of **22 characters**.
+- Encoding and decoding are exact inverses: any UUID → short ID → UUID returns the
+  original UUID. Decoding also accepts an already-full UUID and normalizes it.
+- Resolving an inbound id accepts either form (short ID or full UUID) and yields the
+  UUID, or nothing when the input is not a valid identifier.
+
+Rules:
+- Ids are never hand-formatted when producing output: serializing a resource emits
+  its short ID automatically.
+- Inbound ids (path parameters, and body fields that reference other resources) are
+  resolved to UUIDs before use.
+- A foreign key holds the referenced resource's UUID id.

package/prompts/010-base-model.md

@@ -0,0 +1,27 @@
+---
+id: 010-base-model
+kind: core
+depends_on: [000-uuid]
+---
+# Resources
+
+The application is organized as a set of **resources** (entities). Every resource:
+
+- Has a unique **id** that is a UUID (represented externally as a short ID — see
+  Identifiers).
+- Records **created** and **updated** timestamps, maintained automatically.
+- Is **persistable**: it can be created, fetched by id, listed, updated, and deleted.
+- Has a canonical **serialized form** (its fields as data) used when returned to a
+  client; ids in that form are short IDs.
+
+Modeling rules:
+
+- Each resource is defined once, in its own unit named after the resource.
+- Fields have explicit types and nullability; required fields are enforced.
+- A resource may reference another by holding that resource's id as a **foreign key**;
+  state the delete behavior (cascade when the reference is an owned child, restrict
+  otherwise).
+- Uniqueness rules (single-field or composite) are declared on the resource.
+
+The shared behavior (id, timestamps, persistence, serialization) comes from a common
+base — extend it, do not reimplement it per resource.

package/prompts/020-routes.md

@@ -0,0 +1,23 @@
+---
+id: 020-routes
+kind: core
+depends_on: [010-base-model]
+---
+# Endpoints
+
+Resources are exposed over HTTP as account-scoped REST endpoints. For a resource
+`things`, under the base path `/accounts/{account_id}/things`:
+
+- **list** — read the collection.
+- **create** — add to the collection; validate required fields first.
+- **get** — read one by id.
+- **update** — modify one by id (when the feature calls for it).
+- **delete** — remove one by id (when the feature calls for it).
+
+Conventions:
+
+- Ids in paths are short IDs (see Identifiers) and are resolved to UUIDs before use.
+- Return a resource's serialized form; return collections as arrays.
+- Status codes: 200 for reads and updates, 201 for creates, 200/204 for deletes.
+- Endpoints are grouped per resource and wired into the application automatically —
+  do not edit central bootstrap/registration to add them.

package/prompts/030-auth.md

@@ -0,0 +1,16 @@
+---
+id: 030-auth
+kind: core
+depends_on: [020-routes]
+---
+# Authorization & multi-tenancy
+
+The application is multi-tenant: resources belong to an **account**, and endpoints
+are scoped by account in the path (`/accounts/{account_id}/...`).
+
+- Every resource-accessing endpoint is **guarded** by an authentication check.
+- The auth mechanism may be a stub initially, but the guard must be present on all
+  protected endpoints, so that enabling real authentication later is a single,
+  localized change.
+- Ownership is modeled by storing the owning account's (or user's) id as a foreign
+  key; scope queries by it wherever a feature requires ownership.

package/prompts/040-errors.md

@@ -0,0 +1,25 @@
+---
+id: 040-errors
+kind: core
+depends_on: [020-routes]
+---
+# Errors, tests & house rules
+
+Errors:
+
+- Failures return a consistent, structured error payload (a message, optionally a code).
+- Use 400 for invalid input, 404 for a missing resource, 409 for conflicts (e.g. a
+  uniqueness violation).
+
+Tests:
+
+- Every feature ships automated tests covering at least create + read for its
+  resource, and asserting that ids returned to clients are short IDs (22 characters).
+
+House rules:
+
+- Keep changes minimal and localized to the feature at hand.
+- Do not modify shared infrastructure that is provided: the base resource behavior,
+  the application bootstrap/registration, or the test harness.
+- Add no external dependencies beyond the project's stack unless a feature requires it.
+- The application must run with zero external services in its default configuration.