@phyzess/pappra 0.0.0-stage → 0.1.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 phyzess
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# Pappra
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pappra is a portable workspace manager for coding-agent workflows. It keeps workspace configuration, selected project knowledge, checkpoints, recovery context and bounded code navigation in files owned by the workspace rather than in one chat transcript.
+
+Pappra is the manager. External coding hosts, code-graph engines and collaboration controllers are optional integrations, not installation prerequisites.
+
+## Quick start
+
+Requirements: Node.js 24 or later. `pnpm` 12.3.4 is required only for development inside this repository; Git is required only when a command observes repository identity.
+
+The package is published as `@phyzess/pappra`. Run it with `npx` from the target workspace, or install it globally when you use it every day.
+
+```sh
+# In an empty target workspace
+mkdir -p /tmp/pappra-demo
+cd /tmp/pappra-demo
+curl -fsSL https://raw.githubusercontent.com/phyzess/pappra/main/examples/minimal-choices.json -o ./minimal-choices.json
+
+# Preview first. JSON/config mode is non-interactive and does not prompt.
+npx @phyzess/pappra@beta init --config ./minimal-choices.json --json
+
+# Apply the same choices. With no runtime installed, apply intentionally
+# reports external-actions-pending and exits nonzero after writing config.
+npx @phyzess/pappra@beta init --config ./minimal-choices.json --apply --json
+npx @phyzess/pappra@beta doctor --json
+```
+
+`examples/minimal-choices.json` is complete for a host-free, no-graph, single-directory workspace. The example intentionally has no repositories or optional hosts.
+
+`init --json` without `--config` fails closed because JSON mode does not open the interactive wizard; run `npx @phyzess/pappra@beta init` without `--json` in a TTY if you want to enter selections interactively. `--config` and `--json` never prompt.
+
+Development from a checkout works the same way: `pnpm install --frozen-lockfile`, `pnpm build`, then invoke `dist/cli/main.js` by absolute path from the target workspace.
+
+An apply result can be `ok:true` with `status:"external-actions-pending"` and a
+nonzero process exit. That is a successful, partial configuration write, not a
+claim that a runtime or external tool was installed. Inspect `pendingExternalActions`
+and run `doctor` before adding optional integrations.
+
+Optional examples have prerequisites rather than generated files: code-graph and
+host commands require the selected external CLI/support, and collaboration
+requires an explicit controller. They are not needed for the core workflow above.
+
+## What it manages
+
+- **Workspace configuration:** `.pappra/workspace.json` and checkout-local `.pappra/local/machine.json`.
+- **Knowledge:** workspace and private document catalogs with explicit preview/apply operations.
+- **Continuity:** private task checkpoints and bounded advisory resume packets. Resume never grants execution by itself.
+- **Code intelligence:** status, explicit preparation and bounded query for selected repositories. Text/structure fallback is available when the optional graph engine is absent.
+- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration.
+- **Bounded collaboration:** an optional, explicitly controlled one-request workflow. It is not a scheduler or daemon.
+
+## Optional integrations and support
+
+| Capability                                            | Requirement                                              | Default                                                   |
+| ----------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------- |
+| Workspace, init, doctor, checkpoint/resume, knowledge | Node.js only; Git for repository identity                | Core                                                      |
+| Code graph status/prepare/query                       | Optional external code-graph engine                      | Disabled unless selected; text fallback remains available |
+| Host hooks                                            | Explicitly selected Pi, Codex or Claude Code integration | Not installed automatically                               |
+| Collaboration controller                              | Explicit `--controller <fixture\|pi-rpc>`                | No implicit controller                                    |
+
+Host names and external protocol identifiers describe supported integration surfaces. They do not make any host, model, graph engine or private workspace a prerequisite for core use.
+
+## Development checks
+
+```sh
+pnpm check
+```
+
+The check runs the source policy, type checks, formatting, deterministic tests and a local package smoke test. The package smoke test prefers an offline local tarball (falling back to registry resolution when the runner has no offline metadata) and an isolated fixture home/state; it does not install a model or contact a model provider.
+
+## Status and limits
+
+Pappra is development software (`0.1.0-beta.2`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.2`, because pre-release versions are never republished.
+
+The deterministic suite covers synthetic workspaces, fixtures and local process boundaries. It does not establish real-model behavior, native host callability on every platform, CodeGraph completeness, Windows/Linux parity or production performance. A host adapter version pin is an observed support claim, not proof that a particular native installation will load or run correctly.
+
+## License
+
+Pappra is licensed under the MIT License. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+More detail: [quick start](docs/quickstart.md), [API boundaries](docs/api.md), [support and limitations](docs/support.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,16 @@
+# Third-party notices
+
+Pappra depends on the following packages. Runtime dependencies are installed by
+the consumer and are not copied into Pappra source files.
+
+| Package          | Version | License    | Role                   |
+| ---------------- | ------- | ---------- | ---------------------- |
+| `@clack/prompts` | 1.8.1   | MIT        | Interactive prompts    |
+| `zod`            | 4.6.6   | MIT        | Runtime validation     |
+| `@types/node`    | 24.19.1 | MIT        | Development types      |
+| `prettier`       | 3.9.9   | MIT        | Development formatting |
+| `typescript`     | 7.0.2   | Apache-2.0 | Development compiler   |
+
+The package manager `pnpm` is a development tool and is not shipped in the
+published package contents. This notice is informational; it does not replace
+the license texts or attribution supplied by the projects above.

package/assets/integrations/skills/pappra/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: pappra
+description: Use Pappra workspace knowledge, checkpoint/resume, and selected-repository code intelligence from any supported coding agent. Use when a task needs durable handoff context, workspace documents, or bounded code navigation.
+---
+
+# Pappra
+
+Pappra keeps workspace knowledge, continuity, and code navigation outside the
+host transcript. Use the installed `pappra` CLI for durable operations; hooks
+only record bounded lifecycle observations and never start a model, download,
+index, or new writer.
+
+## Start here
+
+1. Read `references/lifecycle.md` before relying on a host lifecycle event.
+2. Read `references/hosts.md` when the host surface is Pi, Codex, or Claude.
+3. Use `pappra checkpoint` / `pappra resume` for handoffs. A stored checkpoint
+   is context, not permission to execute or to trust a previous session.
+4. Use `pappra docs` and `pappra code` only for the workspace selected by the
+   current root. Never infer a workspace from an unrelated session.
+5. For a new bounded collaboration request, build an explicit
+   `pappra/collaboration-goal/1` from the user's objective and named choices,
+   run `pappra collab prepare --goal <file> --domain-root <dir>`, admit against a fresh capability
+   card, then use `pappra collab run` with the reviewed controller. Never turn
+   prose into identity, approval, or capability claims.
+
+## One-request collaboration
+
+`pappra collab prepare --goal <file> --domain-root <dir>` requires an explicit
+shared domain. It validates the canonical domain/tasks/task/private namespace
+before writing any task metadata and again around each write, so a task-root or
+mid-write directory redirect fails closed instead of scattering artifacts. It
+then writes a private task record, assignment, prompt, and resource claims; read
+resources stay read claims. The captured identities also guard live query, finish, disposal and lower RPC artifact writes; after a redirect, no new query/execution/proof/current-result pathname is written. `pappra collab run` requires an explicit `--controller <fixture|pi-rpc>`,
+performs the single admitted launch, and accepts bounded
+`pappra/collaboration-command/1` JSONL on stdin; it emits
+`pappra/collaboration-event/1` JSONL. `query` reads persisted history only and
+reports live ownership as unknown. A `finish` produces one deterministic REPORT;
+only a result whose stored classification was `applied` for the same fixed
+identity/attempt/input may repeat successfully as a duplicate — repeated
+rejections stay rejected. Cancel records and validates intent first: a denied
+intent never calls the native controller. Claims are retained and stop proof is
+never invented.
+
+Use `--controller fixture` only for deterministic, no-model tests; it is a
+restricted explicit fixture, never a silent default. The optional `pi-rpc` controller
+uses the existing owned Pi RPC daily path and preserves required skills, tools,
+MCP, hooks, and model settings; missing capabilities or stale/forged admission
+fail before launch. A native run reports only the current prompt-correlated
+result: terminal success requires a supported terminal reason and no pending
+tool call, so text-plus-toolUse/intermediate, tool-only, empty, old, malformed or
+missing answers are `unknown`; an explicit error is `failed` and an abort is
+`cancelled`. The current result must be published as validated
+`native-current-result/1` evidence; EIO/conflict/symlink/partial publication
+makes delivery `unknown`, not success, and repeated finish reuses verified
+content instead of overwriting it. A clean transport exit is not task success.
+No approval is auto-answered, no cancel is inferred from an acknowledgement, and no new thread or
+arbitrary PID is adopted. Do not launch a model or real user session without
+the task's explicit authorization.
+
+## Boundaries
+
+- Hooks are local and bounded. They do not read transcripts, run commands,
+  call models, fetch the network, or continue a conversation.
+- Missing semantic context stays missing; do not fabricate summaries.
+- Treat unknown ownership, stale bundles, untrusted hooks, and changed host
+  versions as visible conditions, not silent fallbacks.
+- Preserve user settings and unrelated keys when integrating a host.

package/assets/integrations/skills/pappra/references/hosts.md

@@ -0,0 +1,30 @@
+# Host surfaces
+
+## Pi
+
+The integration installs a project extension plus a copied `pappra` skill.
+Pi extensions run with host permissions. Load only a trusted copy from this
+workspace/target; the generated entrypoint imports the fixed Pappra runtime by
+absolute file URL and registers lifecycle handlers only.
+
+## Codex
+
+The integration installs a command-hook entry and merges only Pappra-owned
+entries into `hooks.json`. Existing hooks and unrelated keys are preserved.
+Codex hook definitions are trusted individually; installation is not trust.
+Observed 0.163.0 hook keys do not include a compact event, so compact and
+automatic checkpoint requests remain unsupported.
+
+## Claude Code
+
+The integration installs a command-hook entry and merges only Pappra-owned
+entries into `settings.json`. `SessionStart` and `PostCompact` are distinct;
+matchers, trust, timeout, and output behavior remain host/version-specific.
+Installing a command is not proof it ran.
+
+## Common safety
+
+All surfaces use the event's canonical cwd/root, bounded stdin, a one-second
+local deadline, no transcript reads, no arbitrary configured commands, and no
+network/model/index/session side effects. Paths with spaces or Unicode are
+passed as argv/file URLs, never interpolated into a shell.

package/assets/integrations/skills/pappra/references/lifecycle.md

@@ -0,0 +1,37 @@
+# Lifecycle reference
+
+## Supported mapping
+
+Pappra distinguishes four local lifecycle intents:
+
+| Intent               | Pi                           | Codex                                      | Claude                                     |
+| -------------------- | ---------------------------- | ------------------------------------------ | ------------------------------------------ |
+| `startup`            | `session_start`              | `SessionStart` with source `startup`/`new` | `SessionStart` with source `startup`/`new` |
+| `resume`             | `session_start`              | `SessionStart` with source `resume`        | `SessionStart` with source `resume`        |
+| `compact`            | `session_before_compact`     | unsupported in observed 0.163.0 hook keys  | `PostCompact`                              |
+| `checkpoint-request` | explicit Pappra command/hook | unsupported automatic event                | unsupported automatic event                |
+
+The matrix is version-specific. A host version outside the observed support
+range is `unsupported`/`unknown`, not a fallback to name similarity.
+
+## What a hook does
+
+A hook validates the host payload, resolves the current workspace from the
+event cwd (never from a last-session cache), derives a bounded event identity,
+suppresses a duplicate identity, and records a private local event observation.
+It may print a short advisory context. It never starts a model, fetches,
+indexes, runs arbitrary commands, creates a new agent, or writes a checkpoint
+with invented semantics.
+
+## Manual continuity
+
+`pappra checkpoint --task <id> ...` and `pappra resume <id>` remain available
+without hooks. A hook observation is not a checkpoint and does not grant
+`executionAllowed`. A resume packet is read-only context; an unknown or
+non-stopped writer fails closed.
+
+## Reload and trust
+
+Installing files does not prove the host loaded them or trusted their exact
+definition. Report reload-needed and trust-needed separately. Do not approve a
+host trust prompt on the user's behalf.

package/assets/integrations/skills/pappra/references/operations.md

@@ -0,0 +1,14 @@
+# Operations reference
+
+- `pappra init` plans or applies workspace configuration.
+- `pappra doctor` is passive: it does not install hooks, start hosts, or fix
+  state.
+- `pappra checkpoint` writes a task checkpoint; `pappra resume` reads a
+  stored snapshot and reports whether execution is allowed.
+- `pappra docs` manages knowledge documents.
+- `pappra code` operates on an explicitly selected repository and keeps
+  index mutations behind an explicit `--apply`.
+
+Preserve user bytes. If an operation reports a conflict or residual path,
+inspect that path and resolve ownership before retrying. Never delete an
+unknown file to make a retry succeed.

package/assets/manifest.json

@@ -0,0 +1,4 @@
+{
+  "schema": "pappra/assets/1",
+  "stage": "toolchain"
+}

package/dist/app/collaboration.d.ts

@@ -0,0 +1,170 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import { type CollaborationEvent, type CollaborationGoal, type CollaborationPrepared } from '../schemas/collaboration.js';
+import { admitLaunch } from '../collab/admission.js';
+import type { Assignment } from '../collab/contracts.js';
+export type CollaborationFailureStatus = 'invalid' | 'needs_input' | 'conflict' | 'unsupported' | 'failed';
+export interface CollaborationFailure {
+    readonly ok: false;
+    readonly status: CollaborationFailureStatus;
+    readonly code: string;
+    readonly message: string;
+    readonly nextAction: string | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export type CollaborationResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | CollaborationFailure;
+export interface PrepareOptions {
+    readonly domainRoot: string;
+    readonly clock?: number;
+}
+export interface PreparedBundle {
+    readonly prepared: CollaborationPrepared;
+    readonly goal: CollaborationGoal;
+    readonly assignment: Assignment;
+}
+export interface StartOptions {
+    readonly capabilitiesFile: string;
+    readonly controller: CollaborationController;
+    readonly controllerId: string;
+    readonly clock?: number;
+}
+export interface ControllerStartRequest {
+    readonly prepared: CollaborationPrepared;
+    readonly goal: CollaborationGoal;
+    readonly assignment: Assignment;
+    readonly capabilitiesFile: string;
+    readonly prompt: string;
+    readonly promptFile: string;
+    readonly taskRoot: string;
+    readonly evidenceDir: string;
+    readonly namespace?: PrivateNamespace;
+}
+export interface ControllerObservation {
+    readonly status: string;
+    readonly detail: string | null;
+    readonly data: unknown;
+}
+export interface ControllerCancel {
+    readonly acknowledged: boolean;
+    readonly terminal_observed: boolean;
+    readonly stop_evidence: unknown;
+}
+export interface ControllerFinish {
+    readonly outcome: string;
+    readonly status: string;
+    readonly exitCode: number | null;
+    readonly sessionId: string | null;
+    readonly outputs: readonly unknown[];
+    readonly nativeRef: unknown;
+    readonly evidenceRef: string | null;
+}
+export interface ControllerSession {
+    query(): Promise<ControllerObservation>;
+    cancel(): Promise<ControllerCancel>;
+    finish(): Promise<ControllerFinish>;
+    dispose?(): Promise<void>;
+}
+export interface CollaborationController {
+    readonly id: string;
+    start(token: object, request: ControllerStartRequest): Promise<{
+        readonly ok: true;
+        readonly session: ControllerSession;
+    } | {
+        readonly ok: false;
+        readonly status: CollaborationFailureStatus;
+        readonly code: string;
+        readonly message: string;
+        readonly nextAction: string | null;
+        readonly possible_start?: boolean;
+    }>;
+}
+interface NamespaceIdentity {
+    readonly path: string;
+    readonly canonical: string;
+    readonly dev: number;
+    readonly ino: number;
+}
+export interface PrivateNamespace {
+    readonly domain: NamespaceIdentity;
+    readonly taskRoot: NamespaceIdentity;
+    readonly privateDir: NamespaceIdentity;
+}
+export declare function validateLaunchToken(token: unknown, expected: {
+    readonly taskRoot: string;
+    readonly assignmentDigest: string;
+    readonly subtaskId: string;
+    readonly attempt: number;
+}): boolean;
+export declare function prepareCollaboration(input: unknown, options: PrepareOptions): Promise<CollaborationResult<PreparedBundle>>;
+export interface AdmissionResult {
+    readonly prepared: CollaborationPrepared;
+    readonly goal: CollaborationGoal;
+    readonly assignment: Assignment;
+    readonly admission: Awaited<ReturnType<typeof admitLaunch>>;
+    readonly token: object;
+}
+export declare function admitPrepared(preparedFile: string, capabilitiesFile: string, options?: {
+    readonly clock?: number;
+}): Promise<CollaborationResult<AdmissionResult>>;
+export interface StartedRun {
+    readonly prepared: CollaborationPrepared;
+    readonly goal: CollaborationGoal;
+    readonly assignment: Assignment;
+    readonly token: object;
+    readonly controller: CollaborationController;
+    readonly session: ControllerSession;
+    readonly reservationId: string | null;
+}
+export declare function startPrepared(preparedFile: string, options: StartOptions): Promise<CollaborationResult<StartedRun>>;
+export interface ReportResult {
+    readonly ok: boolean;
+    readonly messageId: string;
+    readonly duplicate: boolean;
+    readonly classification: string | null;
+    readonly detail: string | null;
+}
+export declare function submitResultReport(started: StartedRun, finish: ControllerFinish, { clock }?: {
+    clock?: number;
+}): ReportResult;
+export declare function finishStarted(started: StartedRun): Promise<CollaborationResult<ControllerFinish>>;
+export declare function driveRun(started: StartedRun, commands: AsyncIterable<unknown>, emit: (event: CollaborationEvent) => void, { clock }?: {
+    clock?: number;
+}): Promise<CollaborationResult<ReportResult>>;
+export declare class FixtureController implements CollaborationController {
+    private readonly options;
+    readonly id = "fixture";
+    constructor(options?: {
+        readonly status?: 'completed' | 'failed' | 'cancelled' | 'needs_input';
+        readonly outputs?: readonly unknown[];
+        readonly sessionId?: string;
+    });
+    start(token: object, request: ControllerStartRequest): Promise<{
+        readonly ok: true;
+        readonly session: ControllerSession;
+    } | {
+        readonly ok: false;
+        readonly status: CollaborationFailureStatus;
+        readonly code: string;
+        readonly message: string;
+        readonly nextAction: string | null;
+        readonly possible_start?: boolean;
+    }>;
+}
+export declare class PiRpcController implements CollaborationController {
+    readonly id = "pi-rpc";
+    start(token: object, request: ControllerStartRequest): Promise<{
+        readonly ok: true;
+        readonly session: ControllerSession;
+    } | {
+        readonly ok: false;
+        readonly status: CollaborationFailureStatus;
+        readonly code: string;
+        readonly message: string;
+        readonly nextAction: string | null;
+        readonly possible_start?: boolean;
+    }>;
+}
+export declare function inspectPreparedHistory(preparedFile: string): CollaborationResult<Record<string, unknown>>;
+export {};