diff --git a/.dockerignore b/.dockerignore index c80bfe4d..6641a3a8 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,3 +1,4 @@ +# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 .git .venv .forge diff --git a/.gitattributes b/.gitattributes index b24b40a9..f628fd9a 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1 +1,2 @@ +# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 studio/public/licenses/markdown-LICENSES.txt whitespace=-blank-at-eof diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2ebb3826..3f6060b9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,3 +1,4 @@ +# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 name: Verify on: push: diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e6878f02..8c55f649 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,3 +1,4 @@ +# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 name: Documentation on: push: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 901ef422..3f06c453 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,3 +1,4 @@ +# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 name: Release on: push: diff --git a/.gitignore b/.gitignore index 3fb7bf8c..a18fb65b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 .venv/ .forge/ .env diff --git a/.prettierignore b/.prettierignore index 0b7ae3a8..03b9fd2b 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,2 +1,3 @@ +# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 # Preserve checksummed licensed framework knowledge sources. src/firefly_forge/resources/knowledge/ diff --git a/CHANGELOG.md b/CHANGELOG.md index f7af6131..545aae53 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Changelog + + ## 0.1.0 — 2026-10-11 - Introduce the Firefly Forge software factory, PyFly control plane and web Studio. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c193353..2eeab50d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,7 @@ # Contributing + + Open an issue describing the behavior and how to reproduce it. Keep changes focused and match existing conventions. Use Python 3.13+, Node.js 22+ and Git. ```sh diff --git a/Dockerfile b/Dockerfile index b4bbf7b8..ab070753 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,3 +1,4 @@ +# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 FROM node:22-bookworm-slim AS studio WORKDIR /build/studio COPY studio/package*.json ./ diff --git a/Makefile b/Makefile index 2b658e78..e4fe19d9 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,4 @@ +# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 .PHONY: check python-check studio-check docs docs-check docs-pages-check package serve check: python-check studio-check docs-check diff --git a/README.md b/README.md index 80d87bca..c3826740 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # firefly forge + + ![firefly forge: from brief to verified software](assets/banner.svg) firefly forge is the Firefly software factory. Describe a product's users, journeys and acceptance checks, connect its repositories, then choose a stack and coding provider. Review the implementation, actual checks and retained evidence before publishing a pull request. diff --git a/SECURITY.md b/SECURITY.md index a5a6c15d..884ea89f 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,7 +1,17 @@ # Security -Report vulnerabilities privately through GitHub Security Advisories for this repository. Include the affected release, a reproduction and the expected trust boundary. Do not publish working credentials or sensitive customer source. + -Forge 0.1 is a single-operator development factory. A token grants access to repository source, generated code, worker commands and publication. Run it on a dedicated trusted development host, bind to loopback, and use TLS/access controls when exposing it remotely. CLI sandboxes and confined Agentic file tools do not constitute a multi-tenant operating-system sandbox for verification commands. Never connect an untrusted repository to a host holding unrelated production credentials. +Report vulnerabilities privately through GitHub Security Advisories for this repository. Include the affected release, a reproduction with synthetic data and the expected trust boundary. Exclude working credentials, private logs and sensitive customer source. -Secrets use environment configuration and Git credential helpers. Generated artifacts exclude private paths. Interrupted runs require an explicit retry. Pull-request publication requires passing verification; Forge never merges generated changes. +firefly forge is a software factory with native pyfly authentication, project permissions, PostgreSQL persistence and one execution leader. Shared installations use Keycloak OIDC, an exact API audience and protected server sessions. Explicit local bootstrap is restricted to its configured loopback mode. Current identity, project and repository authority must permit execution and later effects; a queued request does not renew that authority. + +Host coding and verification execute with the service account's filesystem and process access and require current administrator authority. Project users need an available isolated runner. Use a dedicated service identity and private retained storage. Confined file tools and a coding CLI's permission controls do not establish operating-system isolation for the complete factory. Keep unrelated production credentials and host sockets out of project execution environments. + +Owner-private configuration files and immutable credential revisions protect selected service secrets through filesystem permissions. Connection OAuth credentials are separately encrypted in PostgreSQL under the installation's shared encryption key. Browser consent, token exchange, refresh and scoped resource use have retained policy, actor, project and effect checks. Unknown provider responses require reconciliation. Local disconnect stops factory use and erases active tokens; provider-side authorization must be revoked separately. + +The implemented local OAuth service requires explicit development settings, different literal factory/provider hosts and its fixed read-only resource. Vendor OAuth templates remain inactive until their provider contracts and scoped adapters are admitted. Schema discovery, exact review and repository/tool grants remain mandatory even after consent. Current authorization also applies when returning cached tool receipts. + +Write-ahead intents and receipts retain execution evidence. A database rollback, restart or timeout cannot establish that an external effect did not happen. Observe the exact remote outcome before another publication, deployment or knowledge write. Passing checks and matching source evidence precede delivery; forge does not merge generated changes automatically. + +Keep factory PostgreSQL, private credential revisions, source workspaces, flycanon data and original objects in a consistent backup. Test restoration and unresolved-effect recovery in an isolated installation. Production cluster isolation, live vendor integrations and generated-product deployment need their own acceptance evidence. See the [security guide](docs/security.md) and [factory infrastructure guide](docs/factory-infrastructure.md). diff --git a/compose.yaml b/compose.yaml index 24d3d12d..a8768fab 100644 --- a/compose.yaml +++ b/compose.yaml @@ -1,3 +1,4 @@ +# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 services: forge: build: . diff --git a/docs/agent-integrations.md b/docs/agent-integrations.md index 1205f081..761b3c60 100644 --- a/docs/agent-integrations.md +++ b/docs/agent-integrations.md @@ -4,6 +4,8 @@ description: Operate forge through the Python SDK, CLI and MCP with authenticate # Operate products from Python, the CLI or MCP + + The Python client, CLI and MCP tools call the same authenticated factory API. Project operations, source inspections, product conversations and worker questions use the factory's permissions, revisions and durable receipts. The clients use the running factory and its execution lease. Set `FORGE_URL` to the running factory and provide `FORGE_API_TOKEN` through your operator environment. Source-control credentials remain in the factory's application or OAuth configuration; do not put the operator token in an issue comment or product brief. diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md index d8cd36d2..bdc18cb8 100644 --- a/docs/agent-lifecycle.md +++ b/docs/agent-lifecycle.md @@ -4,6 +4,8 @@ description: Inspect participants, skills, knowledge access and handoffs through # Agent lifecycle + + Use **Agents & skills** to follow work from a product decision through source delivery and application operation. The lifecycle catalog distinguishes AI dialogue, a run-selected coding provider, and deterministic services. A participant describes an implemented service or instruction binding; it is not evidence that a model session or external action has occurred. diff --git a/docs/agent-roles.md b/docs/agent-roles.md index 5acee0e2..d620f8e5 100644 --- a/docs/agent-roles.md +++ b/docs/agent-roles.md @@ -4,6 +4,8 @@ description: Configure factory roles and community skill instructions, with expl # Factory roles and community skills + + A role assigns responsibility to an actual factory stage. It does not create a separate model session. The default implementation uses one selected coding provider, deterministic planning and source checks, real repository verification, and an optional explicitly configured assurance reviewer. ## Responsibilities and execution diff --git a/docs/api.md b/docs/api.md index 3e0866e6..99598cde 100644 --- a/docs/api.md +++ b/docs/api.md @@ -169,4 +169,4 @@ Provider configuration accepts `{"values":{"model":"MODEL","api_key":"PRIVATE_KE Project policies accept `{"skills":["implementation","verification","security"]}`. Omitting `skills` when creating a run uses project defaults; an explicit empty array selects no optional policies. Core framework integration, source safety and verification cannot be disabled. -See [SCM](scm.md) for repository discovery, OAuth redirects and grants; [knowledge](knowledge.md) for source selection and project scopes; and [deployment](deployment.md) for target commands, source checks and rollback requests. +See [connected accounts](connected-accounts.md#api-and-client-contract) for typed service policy, client registration, browser consent and effect receipts; [SCM](scm.md) for repository discovery, OAuth redirects and grants; [knowledge](knowledge.md) for source selection and project scopes; and [deployment](deployment.md) for target commands, source checks and rollback requests. diff --git a/docs/architecture.md b/docs/architecture.md index 59a99b7c..9ddcd7a7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -22,7 +22,7 @@ The factory itself uses [pyfly](https://fireflyframework.org/frameworks/python/)
The same services support a combined process and split admission/execution. Read the arrows as responsibility boundaries; coding providers, Git and knowledge services produce effects outside a database transaction.
-`create_runtime()` constructs the native `PyFlyApplication`, registers `ForgeBeans` and the typed controllers/repositories, then lets the container inject their dependencies. `create_application()` adds the Starlette adapter, request limits, trusted-host middleware and Studio's static build. The worker uses the runtime without an HTTP listener. +`create_runtime()` constructs the native `PyFlyApplication`, registers `FactoryConfiguration` and the typed controllers/repositories, then resolves their registered dependencies through the container. Domain services also retain explicit collaborators and test seams; this does not establish that every construction path is container-owned. `create_application()` adds the Starlette adapter, request limits, trusted-host middleware and Studio's static build. The worker uses the runtime without an HTTP listener. | Layer | Concrete implementation | Contract | | --- | --- | --- | @@ -35,7 +35,36 @@ The factory itself uses [pyfly](https://fireflyframework.org/frameworks/python/) Lifecycle ordering initializes `Store` before topology and execution consumers. The engine acquires ownership before recovering retained work. Worker supervision watches coding, delivery, deployment, campaign, channel and application-observation consumers. A stopped required consumer degrades execution readiness; shutdown closes dispatch and drains effects before releasing ownership. See [runtime roles](runtime-roles.md). -Source: [`api.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/api.py) (`ForgeBeans`, `create_runtime`, `create_application`), [`worker_runtime.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/worker_runtime.py) (`WorkerSupervision`). +### Native knowledge services + +`FactoryConfiguration.knowledge_connection()` injects the private `ConfigurationStore` into `KnowledgeConnection`. `knowledge_manager()` injects `Store`, `Engine`, `Journal`, that connection and `KnowledgeFirst`; it connects the same manager to execution and native knowledge-first tools. `KnowledgeController` uses typed pyfly mappings for configuration, authentication tests, scoped search, source indexing and verified memory. `KnowledgeUploads` has its own injected repository for retained source-upload evidence. + +The connection owns authenticated SDK transport and TLS trust. The manager chooses the frozen connection revision, confines repository scope and handles source/canonical receipts. `KnowledgeFirst` combines those cited references with eligible PostgreSQL procedure outcomes before considering configured web search. It cannot treat a search hit as an approved procedure. + +Flycanon's server runs in a separate environment, with its own migration and ingestion worker. Installing the Python SDK into forge supplies the client; the managed server image installs the released server independently. No flyquery bean, controller, client dependency or analytics worker is registered in this runtime. + +Source: [`api.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/api.py) (`FactoryConfiguration`, `create_runtime`, `create_application`), [`worker_runtime.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/worker_runtime.py) (`WorkerSupervision`). + +### Connection OAuth and resource custody + +`FactoryConfiguration` registers `OAuthProviderPolicies`, `ConnectionOAuth`, `OAuthResources` and the external MCP registry as separate native beans. Policy admission fixes the issuer, endpoints, resource and scope. The connection service binds client registration and browser attempts to the current actor and immutable revision; it uses public pyfly OAuth client and PKCE APIs. PostgreSQL stores encrypted credentials, grant families, effects and append-only events. + +`OAuthResources` signs a project/resource binding and rechecks current policy, registration, grant family/revision, expiry and project authority before dispatch. A schema review and exact repository/tool grant remain mandatory. Current authorization also protects cached broker receipts: a completed result cannot bypass a withdrawn policy or revoked grant. + +
+ + + Admit a fixed service, retain client registration, authorize in the browser, record token effects, bind the exact project resource, and review schemas and tool grants before broker dispatch. + + +[Open full diagram](diagrams/architecture-oauth.svg) · [Portrait layout](diagrams/architecture-oauth-narrow.svg) + +
Consent retains an account grant. Current resource custody, exact schemas and project tool admission remain separate checks.
+
+ +The implemented local service is administrator-only and requires explicit development flags, literal loopback addresses and different factory/provider hosts. The native browser qualification used IPv4 for forge and IPv6 for the owned stock pyfly service. GitHub, Figma, Sentry, Grafana and external Playwright OAuth retain their provider prerequisites. [Connected accounts](connected-accounts.md) explains the actual wizard, typed API and separate MCP admission steps. + +Source: [`oauth_provider_policies.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/oauth_provider_policies.py), [`connection_oauth.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/connection_oauth.py), [`oauth_resources.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/oauth_resources.py), [`mcp_registry.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/mcp_registry.py). ## PostgreSQL records and transaction boundaries @@ -219,7 +248,7 @@ Pinned community skills are instruction adaptations with retained source, hash a | Official Codex / Claude Code | The official CLI's native tools and permission controls | A Python role tool list is advisory; it is not the CLI sandbox. | | Native browser QA | Fresh Docker context, declared local origin and bounded actions | Layout diagnostics and screenshots require actual visual/interaction review. | | Internet search | Explicit Brave or Tavily selection, retained credential revision and domain restrictions | Bounded cited results are untrusted references; no key goes to the model. | -| Factory MCP | 96 authenticated operator tools in `mcp_server.py` | These API tools are distinct from a coding model's workspace tools. | +| Factory MCP | 108 authenticated operator tools in `mcp_server.py` | These API tools are distinct from a coding model's workspace tools. | Flycanon retrieves `forge-` project context and shared framework references. Required retrieval failure prevents coding continuation. The retained citations/context digest support recovery. A ProductProject does not automatically create an aggregated memory workspace across its repositories. @@ -231,6 +260,12 @@ Source: [`agent_roles.py`](https://github.com/fireflyframework/firefly-forge/blo The [learning architecture](learning.md) defines exact reuse eligibility, evidence-backed local procedure outcomes, observed failed checks and typed question/tool/review associations. Its diagrams separate PostgreSQL decision authority from flycanon retrieval and show where native fireflyframework-agentic workers provide proposals. The initial implementation adds scoped PostgreSQL records, native knowledge-first tools and explicit one-shot flycanon projection. Automatic retrieval from projected learning namespaces, classified negative repair controls and sharing between projects remain open; their contracts do not establish runtime acceptance. +### Structured analytics boundary + +The optional [flyquery](https://github.com/fireflyframework/flyquery) architecture would query explicit, versioned project snapshots through an independently authorized service. It would never receive a direct connection to the factory ledger, retained private directory or flycanon database. Query results remain untrusted analytical evidence; factory records and cited canonical memory retain their existing authority. + +The [structured analytics design](structured-knowledge.md) records the assessed pipeline, known execution gaps, proposed native service boundaries and required authorization, snapshot and write-ahead checks. This release has no forge adapter or managed flyquery deployment. + ## Runner ownership, collection and takeover