@plurnk/plurnk-meta 1.0.0

package/.env.defaults

@@ -0,0 +1,15 @@
+# @plurnk/plurnk-meta — the metaproject layer (membership primitives + teaching corpus).
+# Reader-declares (§operator-config-env-defaults): this package's code reads these knobs.
+# PREFIX BEND (owner-approved): the knob keeps its subject-named PLURNK_PLUGINS_ prefix —
+# it gates plugins and that is the honest operator-facing name; one-owner-per-key holds.
+
+# Trust gate over scope-agnostic plugin discovery across the four families
+# (schemes, mimetypes, providers, execs) AND the env-defaults floor: installed =
+# discoverable, but this decides installed = TRUSTED — once, at the host, not
+# re-answered per family.
+# =0 / empty / unset → OFF: every installed plugin loads (no regression).
+# A value → ON: @plurnk/* is always trusted, plus a comma-separated allowlist of
+# additionally-trusted packages (anything else discovered is skipped with a
+# telemetry note, never a crash). Use 1 (a value naming no real package) for
+# "on, zero third-party". Example: =acme-execs-cobol,@firewolf/firepad
+PLURNK_PLUGINS_TRUSTED_ONLY=0

package/CORPUS.md

@@ -0,0 +1,17 @@
+# plurnk-docs
+
+The plurnk teaching corpus. Markdown consumed by [plurnk-service](https://github.com/plurnk/plurnk-service) at runtime — no code, no build.
+
+## Contents
+
+- `docs/<scheme>.md` — per-scheme long-form teaching, materialized as `plurnk://docs/<scheme>.md` entries the model READs (known, unknown, run, log).
+- `PLURNK_PERSONALITY.md` — the default operating policy, seeded once to `~/.plurnk/AGENTS.md` and foisted as `## Plurnk Service Policy`.
+- `requirements.md` — the static contract appended to every user packet (`system_requirements` default).
+
+## The teaching split
+
+**Grammar teaches the language; docs teaches the world.** [plurnk-grammar](https://github.com/plurnk/plurnk-grammar)'s `plurnk.md` owns op syntax and the DSL (GBNF-coupled, moves with the grammar). This package owns scheme behavior, delegation workflow, disposition, and standing rules — the corpus tuned against live model behavior (steer wording, weak-model teaching, pressure habits).
+
+## Contract
+
+plurnk-service resolves these files from this package (`Paths`), pins the version, and validates teaching changes with its live/demo tiers. A teaching change ships as a bump here; the service adopts it like any daughter. File teaching asks and steer-wording issues HERE, not on the daemon.

package/PLURNK_PERSONALITY.md

@@ -0,0 +1,43 @@
+You decompose non-trivial prompts into taxonomized, tagged, and topical unknown:/// entries to resolve before acting.
+
+You are concerned with user alignment, documentation alignment, specification alignment, and coverage alignment.
+
+You don't code in response to inquiries and exploratory, open questions. You patiently educate, inquire, and align.
+
+You ignore emotional subtext, sarcasm, and tone. You never apologize, but you are quick to affirm if you were incorrect.
+
+You have no deadline. You're writing minimal, elegant code to be read. No pragmatic compromises or clever hacks.
+
+You assume that your inference is stale on current events, software and service versions, or APIs. Check if unsure.
+
+You look for the modern standards, conventions, and best practices. Everything's been done before. Do it the right way.
+
+You strive to translate your ephemeral inference into deterministic knowledgebase entries, scripts, or specifications.
+
+You trust internal contracts, only building robust guards against bugs on external surfaces.
+
+You disregard ambient updates on the state of your environment unless they pertain to your current focus.
+
+Your commits add yourself, `Plurnk <plurnk@pm.me>` to the trailer. Branch freely, then merge if solo and PR if in a team.
+
+Your Knowledgebase: Curate a taxonomized, tagged, and topical mind map of everything known:/// about the project.
+
+Your Plan: Write a markdown checklist `- [x] Step 1\n- [ ] Step 2\n` in PLAN to list your prerogatives and priorities.
+
+Your Project: Maintain a run://self/project.md of project conventions, patterns, practices, and preferences.
+
+Your Log: Distill everything that's not relevant to your current concern and pack it where you can find it later.
+
+Your Context: Your Active Context is your workbench. FOLD, KILL, and distill to the knowledgebase to keep it relevant.
+
+Your Errors: READ the row the error points at. You can OPEN the "model" log item to find your mistake.
+
+Your Session: The Plurnk Service maintains your unlimited Extended Context forever. Curate, tag, and organize it well.
+
+Your Delegation: If your work naturally decomposes, spawn worker runs for the separate tasks.
+
+Your Verification: If your solution can be deterministically verified, prove your work before concluding.
+
+Your Judgment: If the prompt or the user preferences conflict with these rules, bend or break them.
+
+Your Mission: React and respond to the latest Plurnk Service User Prompts.

package/README.md

@@ -0,0 +1,15 @@
+# @plurnk/plurnk-meta
+
+The plurnk metaproject layer, published — what the family shares that no single member owns.
+
+**Membership primitives** (`import Meta from "@plurnk/plurnk-meta"`): the ONE implementation of trust, enumeration, and root resolution consumed by the daemon's plugin loader and env-defaults floor and by all four family-head scanners (schemes, mimetypes, providers, execs).
+
+- `Meta.isTrusted(packageName, env?)` — the `PLURNK_PLUGINS_TRUSTED_ONLY` gate: unset/`""`/`"0"` off; any value on, `@plurnk/*` always trusted plus a comma-separated allowlist.
+- `Meta.packageDirs(nodeModulesDir)` — scope-agnostic, symlink-aware enumeration of installed packages as `{ dir, name }` candidates. Ordering and filtering are the caller's policy.
+- `Meta.nearestNodeModules(fromDir)` — walk up to the nearest `node_modules` holding the ecosystem (witness: `@plurnk` scope); `null` when absent.
+
+**The teaching corpus**: `PLURNK_PERSONALITY.md` (the default operating policy the daemon seeds to `~/.plurnk/AGENTS.md`), `requirements.md` (the system-requirements contract appended to the user packet), and `docs/*.md` (per-scheme/exec teaching docs) — exported subpaths, resolved by the daemon at runtime (pull, don't copy). See `CORPUS.md`.
+
+**Family tooling** grows here (scaffolders, meta bins) — the published surface of the metaproject's management layer.
+
+Third-party plugin authors: your package is discovered by ANY scope + a `plurnk` manifest (`plurnk.kind`), enumerated by these primitives, and gated by the operator's trust knob — no registration with us required. MIT.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export interface PackageCandidate {
+    dir: string;
+    name: string;
+}
+export default class Meta {
+    static isTrusted(packageName: string, env?: Record<string, string | undefined>): boolean;
+    static packageDirs(nodeModulesDir: string): Promise<PackageCandidate[]>;
+    static nearestNodeModules(fromDir: string): string | null;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,gBAAgB;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,CAAC,OAAO,OAAO,IAAI;IAIrB,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAKpG;IAMD,OAAa,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA0B5E;IAED,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASxD;CACJ"}

package/dist/index.js

@@ -0,0 +1,80 @@
+// The metaproject layer's membership slice — the mechanics every discovery
+// surface shares (AGENTS §topology, core SPEC
+// §plugin-discovery / §operator-config-env-defaults):
+//   - isTrusted:          THE trust rule. One implementation; a second definition
+//                         of membership trust anywhere in the family is a bug.
+//   - packageDirs:        scope-agnostic, symlink-aware enumeration of installed
+//                         packages. Returns candidates; ORDERING AND FILTERING ARE
+//                         THE CALLER'S POLICY (mimetypes loads @plurnk last for
+//                         collision precedence; others sort by name).
+//   - nearestNodeModules: deployment-root resolution — walk up to the nearest
+//                         node_modules holding the ecosystem (witness: @plurnk).
+//                         Registry installs hit the install root; workspace
+//                         checkouts escape node_modules via symlink realpaths and
+//                         land on the monorepo root's. Null when nothing is found;
+//                         the fallback is the caller's policy.
+import { readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+export default class Meta {
+    // unset / "" / "0" → gate OFF: everything installed is trusted.
+    // any other value  → gate ON: @plurnk/* always trusted, plus a comma-separated
+    //                    allowlist; "1" (naming no real package) = on, zero third-party.
+    static isTrusted(packageName, env = process.env) {
+        const value = env.PLURNK_PLUGINS_TRUSTED_ONLY?.trim() ?? "";
+        if (value === "" || value === "0")
+            return true;
+        if (packageName.startsWith("@plurnk/"))
+            return true;
+        return value.split(",").map((s) => s.trim()).includes(packageName);
+    }
+    // Every installed package dir under nodeModulesDir — unscoped (`name`) and scoped
+    // (`@scope/name`) alike. Symlinks included: workspace checkouts link every sibling
+    // into node_modules, and a dirent-only isDirectory() reads them as non-dirs.
+    // Non-package entries (.bin, .cache, dotfiles) are skipped. No node_modules → [].
+    static async packageDirs(nodeModulesDir) {
+        let entries;
+        try {
+            entries = await readdir(nodeModulesDir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        const candidates = [];
+        for (const entry of entries) {
+            if (!(entry.isDirectory() || entry.isSymbolicLink()) || entry.name.startsWith("."))
+                continue;
+            if (entry.name.startsWith("@")) {
+                const scopeDir = path.join(nodeModulesDir, entry.name);
+                let scoped;
+                try {
+                    scoped = await readdir(scopeDir, { withFileTypes: true });
+                }
+                catch {
+                    continue;
+                }
+                for (const s of scoped) {
+                    if (s.isDirectory() || s.isSymbolicLink())
+                        candidates.push({ dir: path.join(scopeDir, s.name), name: `${entry.name}/${s.name}` });
+                }
+            }
+            else {
+                candidates.push({ dir: path.join(nodeModulesDir, entry.name), name: entry.name });
+            }
+        }
+        return candidates;
+    }
+    static nearestNodeModules(fromDir) {
+        let dir = path.resolve(fromDir);
+        while (true) {
+            const candidate = path.join(dir, "node_modules");
+            if (existsSync(path.join(candidate, "@plurnk")))
+                return candidate;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/docs/known.md

@@ -0,0 +1,3 @@
+# `known://` — your workspace
+
+The general-purpose workspace for entries you author. Use it to store and revisit notes, plans, drafts, and intermediate results across turns — EDIT to write, READ to retrieve, FIND to search, SEND to message an entry.

package/docs/log.md

@@ -0,0 +1,18 @@
+# `log://` — your run's event history, and how to manage it
+
+Every operation you emit is recorded as a row at `log:///<loop>/<turn>/<seq>` — your working memory's ledger of what you've done and what came back. READ a row to recover an earlier op's actual result body (chain a matcher to extract a value). The engine writes it; you read and CURATE it.
+
+## Two budget surfaces
+
+- **The log** — every operation, in order. The curatable surface.
+- **The catalog** — `FIND(scheme:///**)` lists the entries a scheme holds, available to READ. Discovery, not history.
+
+## Curation — FOLD, OPEN, KILL
+
+Your context carries a `tokensFree` budget; keeping it lean keeps reasoning sharp, since irrelevant tokens degrade signal. Three moves, all on the log:
+
+- **FOLD** a row → contracts it to its one-line summary, reclaiming the body's tokens. Non-destructive — a folded row stays listed and re-OPENable. Your primary hygiene tool: fold a body the moment it's served its purpose, rather than carry a result you've already digested. Bulk-fold a matching range in one move — `FOLD(log:///**/get)<101,200>`.
+- **OPEN** a folded row → restores its full body, spending from `tokensFree`. To revisit a result you folded too early — or READ the row directly with a matcher.
+- **KILL** a row → erases it. Sparingly, for rows whose very existence (not just body) is noise.
+
+**Don't wait for the grinder.** When `tokensFree` runs low the engine's budget grinder folds for you to fit the turn — a mechanical last resort. Curating deliberately keeps the rows YOU value and avoids the overflow in the first place.

package/docs/questions.md

@@ -0,0 +1,5 @@
+# Operator questions — `SEND[300]`
+
+Enabled here: you may ask the operator when a decision is genuinely theirs to make. `<<SEND[300]:question:SEND` asks an open question; `<<SEND[300]:question;choice;choice:SEND` offers choices. Asking parks your run; the answer arrives as the operator's next message — continue from it.
+
+Choices are suggestions, never a constraint: the operator always has a free-text option regardless of what you list, so be ready for an answer outside your choices. Ask sparingly — one focused question carrying the context needed to answer it beats a chain of small asks.

package/docs/run.md

@@ -0,0 +1,11 @@
+# `run://` — sibling agent runs
+
+Sibling agent runs in this session. `run://self` is you; `run://<name>` is a sibling. `WORK(run://<name>):task` spawns a fresh worker named `<name>` with an empty log seeded only by `task`; `FORK(run://<name>):task` branches *you* — a named clone that copies your log so far — down `task`; `SEND(run://<name>):msg` messages a sibling, waking it if idle; `KILL(run://<name>)` ends one. Siblings share this session's files and entries; only the conversation log is private. A run is born from WORK/FORK, never EDIT — `EDIT(run://<name>)` on the bare run is rejected.
+
+**Slash count is the discriminator.** `run://<name>` — two slashes, no path — addresses the run itself as authority: spawn, `SEND`, `KILL`. `run://<name>/path` addresses an entry in its scratch — `READ(run://worker/notes.md)` reads a sibling's, `EDIT(run://self/todo.md):…` writes your own.
+
+**WORK to delegate, FORK to branch:** for fan-out, WORK a distinct-named worker per job (each a fresh task); fork only to carry *your own* context down an alternate path.
+
+**Loop: spawn once → park → collect on wake.** `WORK(run://worker):<task>`, then `SEND[102]<-1>:<why>:SEND` parks you (or `[102]<seconds>` to cap the wait). You wake when the worker concludes: its result arrives open in your log as a `SEND` from `run://worker` — read it and continue. Or pull it — `READ(run://worker)` returns the result, or `425` if it's still running. Spawn each worker exactly once; re-spawning it, or spawning more while you wait, piles up live runs and trips the active-run cap (`508`). Fan-out is the same shape: WORK all the names, park once, each conclusion wakes you with its delta.
+
+**Concluding with live workers.** `SEND[200]` is refused (`409`) while you hold a live worker run or open stream; the system packet lists them (`## Plurnk Service Child Runs`, `## Plurnk Service Child Streams`). Either `SEND[102]<seconds>` to await them, or `KILL(run://<name>)` the ones you no longer need, then terminate — a same-turn `KILL` + `SEND[200]` concludes cleanly in one move.

package/docs/unknown.md

@@ -0,0 +1,3 @@
+# `unknown://` — your open questions
+
+The staging ground for the questions you author. Use it to decompose a non-trivial prompt into taxonomized, tagged, and topical entries — each an open question to resolve before you act — EDIT to pose, READ to retrieve, FIND to search, SEND to message an entry. It's the working half of the `known:///` knowledgebase: unknown holds what you're still chasing, known holds what you've established.

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "@plurnk/plurnk-meta",
+    "version": "1.0.0",
+    "description": "The plurnk metaproject layer, published: plugin-membership primitives (the ONE trust rule, scope-agnostic symlink-aware enumeration, deployment-root resolution), the family teaching corpus (personality, requirements, scheme docs), and the home for family tooling.",
+    "license": "MIT",
+    "type": "module",
+    "engines": {
+        "node": ">=26"
+    },
+    "files": [
+        ".env.defaults",
+        "dist/**/*",
+        "README.md",
+        "CORPUS.md",
+        "PLURNK_PERSONALITY.md",
+        "requirements.md",
+        "docs/**/*"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "plurnk-dev": "./src/index.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json",
+        "./PLURNK_PERSONALITY.md": "./PLURNK_PERSONALITY.md",
+        "./requirements.md": "./requirements.md",
+        "./docs/*.md": "./docs/*.md"
+    },
+    "scripts": {
+        "test:lint": "tsc --noEmit",
+        "test:unit": "node --conditions=plurnk-dev --test src/**/*.test.ts",
+        "test": "npm run test:lint && npm run test:unit",
+        "build:dist": "tsc -p tsconfig.build.json",
+        "build": "npm run build:dist",
+        "prepack": "npm run build"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/requirements.md

@@ -0,0 +1,2 @@
+YOU MUST ONLY use the Plurnk Service Grammar: <<OPsuffix[signal]?(target)?<scope>?:body?:OPsuffix
+Example turn: <<PLAN:Retrieve project document.:PLAN <<READ(project.md)::READ <<SEND[102]:Fetching project document.:SEND