@jslee124/forge 0.3.0 → 0.3.1

package/resources/docs/en/PRODUCT.md

@@ -0,0 +1,157 @@
+# Product Definition
+
+简体中文 · Documentation index
+
+## Summary
+
+Forge is a lightweight, safe-by-default terminal coding agent that can inspect a
+local codebase, use tools, modify files, run commands, and adapt its next action
+to the observed result. Trusted plugins can extend its capabilities without
+replacing mandatory runtime safeguards.
+
+Its distinguishing feature is transparency. A developer should be able to see
+model-provided reasoning when available, what Forge did, why execution stopped,
+how much it cost, and whether the result passed an objective evaluation.
+
+## Target users
+
+### Primary user
+
+A developer who wants to understand and experiment with the internal behavior
+of a coding agent.
+
+### Secondary user
+
+A developer who wants a small, inspectable coding assistant for local tasks and
+prefers explicit behavior over a large, opaque feature set.
+
+## Core use case
+
+```bash
+forge run "Add input validation and update the tests"
+```
+
+The expected user journey is:
+
+1. Forge validates its configuration and workspace.
+2. Forge merges user settings from `~/.forge/` with applicable project settings
+   and instructions, recording their source paths.
+3. Forge asks the model to choose the next action.
+4. The model uses tools to inspect relevant files.
+5. Forge checks each proposed action against its safety policy.
+6. Forge asks for approval when an action crosses a configured boundary.
+7. Forge executes approved actions and records their results.
+8. The model uses those results to decide what to do next.
+9. Forge modifies the code and runs an appropriate verification command.
+10. Forge stops with a truthful summary, or explains why it could not finish.
+
+## Product principles
+
+### Transparent
+
+The terminal should show meaningful model and tool activity. Reasoning or
+thinking content returned by the model provider should be visible to the user by
+default and represented honestly as provider-supplied content. If a model does
+not return reasoning content, Forge must not fabricate or imply access to it. A
+structured trace should preserve the observable execution trajectory for later
+inspection.
+
+### Safe by default
+
+Forge should restrict filesystem access to the selected workspace, limit
+commands and execution time, and require approval for risky operations.
+
+Read-only operations inside the workspace may run automatically. The first
+workspace write requires approval by default, every process command requires
+approval by default, and built-in file tools deny operations outside the
+workspace in v0.1. In non-interactive operation, an action that requires
+approval is denied unless a matching narrow approval was supplied in advance.
+
+### Verifiable
+
+Forge should not treat a plausible final message as proof of completion. When a
+task can be verified with tests, type checking, linting, or another deterministic
+check, Forge should run that check and report its real result.
+
+### Framework-aware, not framework-owned
+
+Forge will use established libraries where they remove incidental complexity,
+but its central runtime concepts should remain visible and independently
+testable.
+
+### Extensible without weakening safeguards
+
+Plugins may add tools, commands, prompt contributions, and controlled lifecycle
+hooks. They must not turn a core `deny` into `allow`, bypass approval, or replace
+the policy kernel. Trusted in-process plugins still execute as local code and
+therefore require an explicit trust decision.
+
+### Small before broad
+
+A narrow, reliable workflow is more valuable than many incomplete features.
+
+## Initial feature set
+
+The first useful version will include:
+
+- A TypeScript command-line interface
+- A multi-line interactive terminal UI with slash-command discovery,
+  workspace-file mentions, and readable diff review
+- DeepSeek as the first provider, authenticated with `DEEPSEEK_API_KEY`
+- Streaming model responses through Vercel AI SDK and `@ai-sdk/deepseek`
+- A multi-step agent loop with explicit stop conditions
+- User-wide configuration through `~/.forge/config.json`
+- Hierarchical repository instructions through `AGENTS.md`
+- Inspectable configuration provenance through `forge config show`
+- Tools for listing, reading, searching, patching, and running commands
+- Workspace path validation
+- Command timeout and cancellation
+- Approval decisions for sensitive actions
+- Visible provider-supplied reasoning when available
+- Structured terminal events and JSONL traces
+- Persistent local sessions that can be resumed after restarting Forge
+- Automated tests for the runtime and tools
+- A canonical fixture task, deterministic recovery scenario, and reproducible
+  release evaluation
+
+## Success criteria for v0.1
+
+Forge v0.1 is successful when it meets the concrete release gates in
+v0.1 Acceptance and Evaluation, including a small repository
+task from end to end:
+
+1. Inspect more than one relevant file.
+2. Make a targeted code change.
+3. Run an automated verification command.
+4. Demonstrate recovery from a failed verification in a deterministic runtime
+   scenario.
+5. Stop after success or a configured limit.
+6. Deny built-in file operations outside the selected workspace.
+7. Produce a trace consistent with its real actions.
+8. Produce a final summary consistent with the actual file changes and command
+   results.
+
+## Out of scope for v0.1
+
+- Multiple cooperating agents
+- Graphical or IDE interfaces
+- Remote execution
+- Persistent semantic memory
+- Retrieval-augmented generation
+- MCP server discovery
+- Third-party plugin package installation
+- Automatic commits, pushes, or pull requests
+- Production-grade operating-system sandboxing
+
+## Future portfolio direction
+
+After the native runtime is reliable, Forge may add:
+
+- A broader evaluation suite with more tasks, trials, graders, and reports
+- OpenAI API-key authentication and, when supported by an appropriate public
+  integration, Codex-compatible Sign in with ChatGPT
+- A LangChain or LangGraph runtime adapter evaluated on the same tasks
+- An HTTP API with Server-Sent Events, cancellation, and human approval
+- SQLite-backed indexing, session branching, and cross-machine synchronization
+
+These are future extensions, not requirements for beginning implementation.

package/resources/docs/en/PROJECT_CONTEXT.md

@@ -0,0 +1,225 @@
+# Project Context and Local Customization
+
+简体中文 · Documentation index
+
+## Goal
+
+Forge understands repository-specific instructions and reusable Agent
+resources without turning repository contents into an implicit permission grant.
+It uses three deliberately separate conventions:
+
+| Location | Purpose | Executable by itself |
+| --- | --- | --- |
+| `AGENTS.md` | Portable, human-readable project instructions | No |
+| `.agents/` | Agent-agnostic reusable resources such as skills | No |
+| `~/.forge/` | User-wide Forge settings, instructions, state, and plugins | Plugins are code |
+| `<workspace-root>/.forge/` | Forge-specific project settings and plugins | Plugins are code |
+
+Repository instructions may shape how the model approaches a task. They cannot
+weaken the policy kernel, approve an action, select `full-access`, or bypass a
+tool's normal approval and trace pipeline.
+
+The implemented system includes schema-versioned user/project configuration,
+instruction discovery and provenance, persistent sessions and traces,
+model-invocable portable Skills, trusted plugins, and strictness-merged
+context budgets.
+
+## `AGENTS.md`
+
+Forge follows the established uppercase filename `AGENTS.md`. On
+case-sensitive filesystems, `agents.md` is a different file and is not an alias.
+It also supports `AGENTS.override.md` for a more specific replacement at a
+directory level.
+
+For a run whose working directory is inside a Git repository, Forge will:
+
+1. Resolve the canonical repository root.
+2. Walk from that root to the run's working directory.
+3. In each directory, load at most one non-empty instruction file, preferring
+   `AGENTS.override.md` over `AGENTS.md`.
+4. Merge instructions from root to leaf so that the nearest file has the
+   highest instruction precedence.
+5. Record every loaded path in the run trace.
+
+Discovery happens once at the beginning of a run. Forge will impose per-file
+and total byte limits and report ignored or truncated instruction files rather
+than silently changing the effective prompt.
+
+These files are prompt input, not trusted policy. A statement such as "run all
+commands without asking" has no effect on the approval policy.
+
+## `.agents/`
+
+`.agents/` is the portable resource namespace. The first supported layout is:
+
+```text
+.agents/
+`-- skills/
+    `-- <skill-name>/
+        `-- SKILL.md
+```
+
+A skill is discovered metadata and instructions; it is never executed merely
+because it exists. If a skill references a script or proposes a tool action,
+that action still uses the normal policy and approval flow. Forge should show
+the source path when a project skill is selected and include the selection in
+the trace.
+
+Forge parses bounded YAML frontmatter (`name`, task-oriented `description`, and
+optional `disable-model-invocation`) and initially sends only escaped catalog
+metadata to the model. Matching Skills are loaded on demand by opaque ID;
+`$skill-name` remains a deterministic override. Project Skills are
+model-invocable by default and require no plugin trust because they are never
+imported or executed. `disable-model-invocation: true` makes one Skill available
+only through an explicit user mention.
+
+The same convention is available for built-in Skills shipped with Forge and
+user Skills under `$FORGE_HOME/skills/`. Collisions resolve as
+`project > user > builtin`, with shadowed sources recorded as diagnostics. New
+portable subdirectories should only be added when there is a clear cross-agent
+convention instead of placing Forge-specific data here.
+
+## User-level `~/.forge/`
+
+Forge uses `~/.forge/` as its default user home. `~` is resolved through the
+operating system rather than relative to the current working directory. A
+`FORGE_HOME` environment variable may override the location for portable
+installations, testing, or managed environments.
+
+The user layout is:
+
+```text
+~/.forge/
+|-- config.json
+|-- AGENTS.md
+|-- skills/
+|-- plugin-trust.json
+|-- plugins/
+|-- state/
+|-- sessions/
+`-- runs/
+```
+
+- `config.json` contains user-wide defaults such as provider, model, limits,
+  context behavior, trace behavior, and the default permission profile.
+- `AGENTS.md` contains optional user-wide instructions loaded before project
+  instructions.
+- `skills/` contains user-wide non-executable Skills discovered as bounded
+  metadata and loaded lazily.
+- `plugins/` contains explicitly installed or enabled user plugins.
+- `state/` contains non-secret Forge state such as project-trust decisions.
+- `sessions/` contains versioned completed conversation snapshots.
+- `runs/` contains local traces when trace persistence is enabled.
+
+Forge may create missing runtime subdirectories, but it must not overwrite an
+existing configuration file. API keys and OAuth tokens do not belong in
+`config.json`; Forge uses environment variables or the credential store defined
+in the authentication model.
+
+### Configuration schema
+
+The Zod schema in `@forge/config` is the executable source of truth. See the
+Configuration reference for every field, default, accepted
+value, environment override, provider-route example, and merge rule.
+
+The security-relevant summary is:
+
+| Scope | May configure | Must not configure |
+| --- | --- | --- |
+| User `$FORGE_HOME/config.json` | Model, engine, provider routes, permission profile, limits, traces, plugins, context | API keys or OAuth credentials |
+| Project `.forge/config.json` | Stricter `limits` and `context` values | Model/provider, permissions, traces, plugin enablement, routes, secrets |
+| Environment | `FORGE_PROVIDER`, `FORGE_MODEL`, `FORGE_REASONING_EFFORT`, `FORGE_THINKING`, and credential variables | Permission widening |
+| Explicit CLI | Supported command-scoped model, permission, limit, and context overrides | Repository trust or secret persistence through arguments |
+
+Unknown fields are errors rather than silently ignored. `FORGE_HOME` changes
+discovery location before configuration is loaded. There is intentionally no
+environment variable that widens the permission profile.
+
+User configuration is loaded before repository configuration. Forge should
+provide `forge config show` to display the effective value and source of every
+setting, and `forge config validate` to report invalid keys and values without
+starting an Agent run.
+
+## Project-level `.forge/`
+
+The selected workspace root's `.forge/` is reserved for Forge-specific project
+customization. The current 0.3.1 layout is:
+
+```text
+.forge/
+|-- config.json
+`-- plugins/
+    `-- <plugin-name>/
+        |-- plugin.json
+        `-- index.mjs
+```
+
+The phrase "project-local" means the selected workspace root's canonical
+`.forge/` directory. Forge will not search arbitrary parent directories or
+nested directories for additional `.forge/plugins/` trees. This keeps plugin
+discovery stable when Forge starts from a repository subdirectory.
+
+Repository configuration may choose model-independent project behavior,
+formatting, and stricter execution limits, but it cannot
+relax the user's permission profile or core safety policy. Security-sensitive
+keys such as the default permission profile, plugin enablement, and project
+trust are user-only.
+Unknown keys and unsupported schema versions must produce actionable
+diagnostics.
+
+Project plugins are trusted executable code. Forge must discover and summarize
+them before loading, then require an explicit trust decision for the canonical
+workspace path. Trust state is stored outside the repository so repository code
+cannot mark itself trusted. In non-interactive mode, untrusted project plugins
+are skipped. An explicit `forge plugins trust --yes` records trust outside the
+project before later runs.
+
+Forge will not automatically install plugin dependencies or run package-manager
+lifecycle scripts during discovery.
+
+## Precedence
+
+For ordinary settings, later sources override earlier sources:
+
+```text
+built-in defaults < ~/.forge/config.json < project .forge/config.json
+                  < environment variables < explicit CLI flags
+```
+
+Every configuration value keeps its source metadata so `forge config show` and
+run traces can explain the effective result. Configuration discovery and merge
+happen once at startup; Forge does not silently change settings during a run.
+The schema classifies keys by scope: user-only security settings reject project
+values, while safety limits use the stricter value instead of ordinary
+last-writer-wins merging.
+
+Security and instruction precedence are intentionally different:
+
+```text
+Security decisions: deny > confirm > allow (strictest contribution wins)
+Instructions: user request > loaded skill > nearest project AGENTS.md
+              > project-root AGENTS.md > ~/.forge/AGENTS.md
+```
+
+Skill name collisions use a separate resource rule:
+
+```text
+explicit $skill-name selection > project > user > builtin
+```
+
+Core policy defines a mandatory safety floor. Explicit CLI choices and user
+configuration may select a supported permission profile, while project content
+and plugins may only make an action stricter. They can never make a mandatory
+decision less strict. The instruction ordering applies only when instructions
+do not conflict with the security boundary or higher-level runtime constraints.
+User-level `~/.forge/AGENTS.md` is loaded before the project hierarchy.
+Forge-specific plugins may contribute prompt instructions only through typed
+hooks, and their source must remain visible in the trace.
+
+## Deferred decisions
+
+- Configuration migrations beyond `schemaVersion: 1`
+- Additional environment-variable mappings beyond the v0.1 model settings
+- Additional Skill manifest and compatibility rules beyond the current
+  `SKILL.md` convention
+- Whether restricted plugins run in a child process or an OS sandbox

package/resources/docs/en/RELEASING.md

@@ -0,0 +1,94 @@
+# npm Release Guide
+
+简体中文 · Documentation index
+
+Forge keeps its implementation packages private and publishes one user-facing
+package: `@jslee124/forge`. The generated package contains the CLI, bundled
+`@forge/*` workspace code, and reviewed version-matched built-in Skill assets.
+Third-party libraries remain ordinary npm runtime dependencies. The plugin SDK
+is not a separately published package.
+
+## Distribution contract
+
+- Install: `npm install --global @jslee124/forge`
+- Command: `forge`
+- Stable npm tag: `latest`
+- Prerelease npm tag: `next`
+- Runtime baseline: Node.js 24 or newer
+- Generated package directory: `dist/npm/forge`
+
+The source package at `apps/cli` remains private. `pnpm build:package` creates
+the public manifest and bundle in the ignored `dist/npm/forge` directory, so
+development-only files cannot enter the registry by accident.
+
+## Prepare a release
+
+Start from a clean checkout and choose a semantic version:
+
+```bash
+pnpm version:set 0.3.0
+pnpm install --frozen-lockfile
+pnpm check
+pnpm check:docs
+pnpm test
+pnpm eval:deterministic
+pnpm package:verify
+pnpm release:verify-tag v0.3.0
+```
+
+`package:verify` builds the public artifact, inspects the tarball, installs it
+into a fresh temporary prefix with lifecycle scripts disabled, verifies the
+exact built-in Skill/reference/template allowlist and API version, and checks
+`forge --version`, `forge --help`, and `forge config validate`.
+
+Review `npm pack --dry-run` output and release notes before tagging. Never
+include API keys, auth files, local traces, `.env` files, or evaluation
+artifacts that were not explicitly reviewed for publication.
+
+## First npm publication
+
+The npm account or organization must control the `@jslee124` scope and have 2FA
+enabled. npm requires a package to exist before a trusted publisher can be
+attached. Bootstrap the package with a reviewed prerelease such as
+`0.3.0-bootstrap.0` under a non-stable dist-tag, then configure the repository's
+`publish.yml` as the package's GitHub Actions trusted publisher. Do not assign
+the bootstrap build to `latest`.
+
+After trusted publishing is configured, stable releases should come only from
+the tag workflow. It uses OIDC instead of a long-lived npm token and publishes
+the generated package after all release gates pass.
+
+## Publish a stable release
+
+Commit the version, release notes, and generated-input changes, then create an
+annotated immutable tag:
+
+```bash
+git tag -a v0.3.0 -m "Forge v0.3.0"
+git push origin v0.3.0
+```
+
+The `Publish npm package` workflow verifies that the Git tag, root version,
+private workspace versions, runtime version, and generated npm package all
+match before it runs `npm publish --access public`.
+
+Use `npm publish --tag next` only for deliberate prereleases. Do not move a
+published Git tag or reuse an npm version. Fix a bad release with a new patch
+version and leave the prior artifact available for rollback.
+
+## User updates
+
+Installed users can check or update explicitly:
+
+```bash
+forge update check
+forge update
+forge update 0.3.1
+```
+
+Interactive startup refreshes an advisory npm check in the background at most
+once per 24 hours and displays cached results on a later launch. It never
+installs an update automatically. Set
+`FORGE_DISABLE_UPDATE_CHECK=1` to disable startup checks. The explicit update
+command resolves npm metadata to an exact semantic version before invoking
+`npm install --global --ignore-scripts`.