From cecccc3693e069e0b8329693f196aee205a73f6b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 3 May 2026 02:00:08 +0000 Subject: [PATCH 1/3] Initial plan From 0c04d0e7da22ae5bded884baa568338d67155e8e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 3 May 2026 02:02:24 +0000 Subject: [PATCH 2/3] feat: add PDF-first runtime scaffold with smoke validation Agent-Logs-Url: https://github.com/SourceOS-Linux/sourceos-shell/sessions/a3e9339f-5058-449b-9d2e-7f901acef9a4 Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com> --- Makefile | 30 ++++++++- README.md | 82 ++++++++++++++++++------ apps/pdf-viewer-demo/package.json | 8 +++ apps/pdf-viewer-demo/src/smoke.js | 11 ++++ services/docd/package.json | 5 +- services/docd/src/derive.js | 12 ++++ services/pdf-secure/package.json | 5 +- services/pdf-secure/src/sign-validate.js | 13 ++++ 8 files changed, 143 insertions(+), 23 deletions(-) create mode 100644 apps/pdf-viewer-demo/package.json create mode 100644 apps/pdf-viewer-demo/src/smoke.js create mode 100644 services/docd/src/derive.js create mode 100644 services/pdf-secure/src/sign-validate.js diff --git a/Makefile b/Makefile index 6aa7efb..12964d9 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,31 @@ +.PHONY: validate smoke up down + +validate: + @echo "==> Validating workspace layout..." + @test -d services/docd || (echo "FAIL: services/docd missing" && exit 1) + @test -d services/pdf-secure || (echo "FAIL: services/pdf-secure missing" && exit 1) + @test -d apps/pdf-viewer-demo || (echo "FAIL: apps/pdf-viewer-demo missing" && exit 1) + @test -d content/draft || (echo "FAIL: content/draft missing" && exit 1) + @test -d content/derived || (echo "FAIL: content/derived missing" && exit 1) + @test -d content/reports || (echo "FAIL: content/reports missing" && exit 1) + @test -f services/docd/src/derive.js || (echo "FAIL: services/docd/src/derive.js missing" && exit 1) + @test -f services/pdf-secure/src/sign-validate.js || (echo "FAIL: services/pdf-secure/src/sign-validate.js missing" && exit 1) + @test -f apps/pdf-viewer-demo/src/smoke.js || (echo "FAIL: apps/pdf-viewer-demo/src/smoke.js missing" && exit 1) + @echo "PASS: validate" + +smoke: + @echo "==> Running smoke tests..." + @echo "--- services/docd ---" + node services/docd/src/derive.js + @echo "--- services/pdf-secure ---" + node services/pdf-secure/src/sign-validate.js + @echo "--- apps/pdf-viewer-demo ---" + node apps/pdf-viewer-demo/src/smoke.js + @echo "PASS: smoke" + up: - docker compose -f infra/compose/docker-compose.yml up --build + docker compose -f infra/compose/docker-compose.yml up --build down: - docker compose -f infra/compose/docker-compose.yml down -v + docker compose -f infra/compose/docker-compose.yml down -v + diff --git a/README.md b/README.md index fe03471..b30300a 100644 --- a/README.md +++ b/README.md @@ -2,29 +2,73 @@ Primary product/runtime repository for the SourceOS shell. -## Boundary +## Repo boundary -- `SourceOS-Linux/sourceos-shell` = product/runtime code -- `SourceOS-Linux/sourceos-spec` = shared machine-readable contracts -- `SociOS-Linux/source-os` = Linux realization surfaces -- `SociOS-Linux/albert` = temporary launcher bridge only +| Repository | Responsibility | +|---|---| +| [`SourceOS-Linux/sourceos-shell`](https://github.com/SourceOS-Linux/sourceos-shell) | Product/runtime code (this repo) | +| [`SourceOS-Linux/sourceos-spec`](https://github.com/SourceOS-Linux/sourceos-spec) | Shared machine-readable contracts | +| [`SociOS-Linux/source-os`](https://github.com/SociOS-Linux/source-os) | Linux realization surfaces | +| `SociOS-Linux/albert` | Temporary launcher bridge only | -## Immediate sequencing +## PDF-first runtime scope -This repository is the runtime home for the broader shell stack, but the first implementation slice is **PDF-first**. +This repository is the runtime home for the broader shell stack. The **first implementation slice is PDF-first**. -Initial runtime scope: -- `services/docd` — derive lane -- `services/pdf-secure` — sign / validate lane -- `apps/pdf-viewer-demo` — PDF viewer/demo surface -- `content/` — draft / derived / reports layout -- minimal workspace/bootstrap files +### Services -Explicitly deferred until after the PDF lane is real: -- notes / graph / gallery / playground surfaces -- broader shell UX expansion -- non-PDF publication features beyond what the PDF lane needs +| Service | Path | Role | +|---|---|---| +| `docd` | `services/docd` | Derive lane — draft → derived PDF | +| `pdf-secure` | `services/pdf-secure` | Sign / validate lane | -## Intent +### Apps -We keep the repo boundary correct without letting the first implementation slice sprawl beyond the PDF/document/runtime lane. +| App | Path | Role | +|---|---|---| +| `pdf-viewer-demo` | `apps/pdf-viewer-demo` | PDF viewer / demo surface | + +### Content layout + +| Directory | Purpose | +|---|---| +| `content/draft` | Source draft documents | +| `content/derived` | Derived PDFs produced by `docd` | +| `content/reports` | Validation reports from `pdf-secure` | + +## Commands + +```bash +# Validate workspace layout (no external services needed) +make validate + +# Run smoke tests for each runtime slice +make smoke + +# Docker compose (requires Docker) +make up +make down +``` + +## Contracts + +Machine-readable contracts for all inter-service boundaries live in +[`SourceOS-Linux/sourceos-spec`](https://github.com/SourceOS-Linux/sourceos-spec). +Do not define contracts in this repo; reference them from `sourceos-spec`. + +## Linux realization + +OS-level realization surfaces (packaging, init, system integration) live in +[`SociOS-Linux/source-os`](https://github.com/SociOS-Linux/source-os). + +## Explicitly deferred + +The following are out of scope until the PDF lane is real: + +- Notes / graph / gallery / playground surfaces +- Broader shell UX expansion +- Non-PDF publication features beyond what the PDF lane needs + +## Status + +All runtime slices are **placeholder scaffolds** — smoke-tested, no external services required. diff --git a/apps/pdf-viewer-demo/package.json b/apps/pdf-viewer-demo/package.json new file mode 100644 index 0000000..251486f --- /dev/null +++ b/apps/pdf-viewer-demo/package.json @@ -0,0 +1,8 @@ +{ + "name": "pdf-viewer-demo", + "private": true, + "type": "commonjs", + "scripts": { + "smoke": "node src/smoke.js" + } +} diff --git a/apps/pdf-viewer-demo/src/smoke.js b/apps/pdf-viewer-demo/src/smoke.js new file mode 100644 index 0000000..08c867b --- /dev/null +++ b/apps/pdf-viewer-demo/src/smoke.js @@ -0,0 +1,11 @@ +#!/usr/bin/env node +// pdf-viewer-demo — smoke placeholder +// Responsibility: PDF viewer/demo surface +// Contracts live in SourceOS-Linux/sourceos-spec + +'use strict'; + +console.log('[pdf-viewer-demo] smoke OK — viewer/demo placeholder running'); +console.log('[pdf-viewer-demo] Serves : apps/pdf-viewer-demo/index.html'); +console.log('[pdf-viewer-demo] Status : placeholder (no external services required)'); +process.exit(0); diff --git a/services/docd/package.json b/services/docd/package.json index e87b885..1a5dc0d 100644 --- a/services/docd/package.json +++ b/services/docd/package.json @@ -1,5 +1,8 @@ { "name": "docd", "private": true, - "type": "module" + "type": "commonjs", + "scripts": { + "smoke": "node src/derive.js" + } } diff --git a/services/docd/src/derive.js b/services/docd/src/derive.js new file mode 100644 index 0000000..8201cd3 --- /dev/null +++ b/services/docd/src/derive.js @@ -0,0 +1,12 @@ +#!/usr/bin/env node +// docd derive — smoke placeholder +// Responsibility: PDF derive lane (draft → derived PDF) +// Contracts live in SourceOS-Linux/sourceos-spec + +'use strict'; + +console.log('[docd] derive: smoke OK — derive lane placeholder running'); +console.log('[docd] Input lane : content/draft'); +console.log('[docd] Output lane : content/derived'); +console.log('[docd] Status : placeholder (no external services required)'); +process.exit(0); diff --git a/services/pdf-secure/package.json b/services/pdf-secure/package.json index 778fad3..c3826b3 100644 --- a/services/pdf-secure/package.json +++ b/services/pdf-secure/package.json @@ -1,5 +1,8 @@ { "name": "pdf-secure", "private": true, - "type": "module" + "type": "commonjs", + "scripts": { + "smoke": "node src/sign-validate.js" + } } diff --git a/services/pdf-secure/src/sign-validate.js b/services/pdf-secure/src/sign-validate.js new file mode 100644 index 0000000..7c43957 --- /dev/null +++ b/services/pdf-secure/src/sign-validate.js @@ -0,0 +1,13 @@ +#!/usr/bin/env node +// pdf-secure sign/validate — smoke placeholder +// Responsibility: PDF sign / validate lane +// Contracts live in SourceOS-Linux/sourceos-spec + +'use strict'; + +console.log('[pdf-secure] sign-validate: smoke OK — sign/validate lane placeholder running'); +console.log('[pdf-secure] Sign input : content/derived'); +console.log('[pdf-secure] Signed output : content/derived/pdf_signed'); +console.log('[pdf-secure] Reports : content/reports/pdf_validation'); +console.log('[pdf-secure] Status : placeholder (no external services required)'); +process.exit(0); From be8cd14406cce24418e585729dbd77c48650e32a Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Sat, 2 May 2026 22:15:29 -0400 Subject: [PATCH 3/3] docs: define SourceOS Shell runtime architecture --- docs/ARCHITECTURE.md | 66 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/ARCHITECTURE.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..a7a9956 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,66 @@ +# SourceOS Shell Architecture + +SourceOS Shell is the product/runtime workspace shell for trusted documents, office workflows, search, provenance, and agent evidence. + +It is not a GNOME Shell replacement in v0. GNOME remains the desktop shell, compositor, panel, and windowing environment for the first Linux realization. SourceOS Shell integrates with GNOME through desktop entries, launchers, file actions, reports, and adapters. + +## Repository boundary + +| Repository | Responsibility | +|---|---| +| `SourceOS-Linux/sourceos-shell` | Product/runtime shell code: document services, PDF runtime, office/workspace actions, UI packages, router/adapters. | +| `SourceOS-Linux/sourceos-spec` | Canonical contracts, schemas, examples, evidence object shapes. | +| `SociOS-Linux/source-os` | Linux realization: host profiles, GNOME defaults, installer, status/doctor, service wiring. | +| `SocioProphet/agentplane` and related repos | Agent execution evidence, policy/control integration, operator surfaces. | + +## Staged model + +### Stage 0: PDF-first runtime + +The first executable slice is intentionally small: + +- `services/docd` derives document artifacts. +- `services/pdf-secure` signs and validates artifact placeholders. +- `apps/pdf-viewer-demo` proves the viewer/demo entry point. +- `content/draft`, `content/derived`, and `content/reports` define the local artifact layout. +- `make validate` and `make smoke` prove the scaffold is callable without external services. + +This does not claim a full PDF engine. + +### Stage 1: Document shell + +The document shell adds artifact manifests, validation reports, sidecars, annotation export, provenance ribbons, and publishing/report surfaces. + +### Stage 2: Office shell + +The office shell adds open/create/search/convert/export/template workflows, with LibreOffice/Collabora-compatible open implementation paths where appropriate. + +### Stage 3: Workspace/action shell + +The workspace shell adds action routing, shell-web surfaces, local report history, agent output inbox, status/doctor/fix report UI, and search-provider routing. + +### Stage 4: GNOME adapter + +The GNOME adapter integrates SourceOS Shell with Linux desktops through launchers, desktop entries, file-manager actions, notifications, portals, and the SourceOS workstation profile. + +### Stage 5: Optional desktop shell path + +A GNOME Shell replacement, compositor adapter, or full SourceOS desktop shell is deferred until the document/runtime shell proves value. This repository must not imply full desktop replacement before that decision gate. + +## Non-goals for this scaffold + +- No full PDF engine. +- No production signing. +- No proprietary dependency requirement. +- No GNOME Shell replacement. +- No host mutation or Linux profile wiring. +- No production readiness claim. + +## Validation + +The scaffold must remain smokeable with: + +```bash +make validate +make smoke +```