diff --git a/docs-site/.gitignore b/docs-site/.gitignore index 88c64668..c911073f 100644 --- a/docs-site/.gitignore +++ b/docs-site/.gitignore @@ -1,6 +1,8 @@ node_modules dist/ +dist-desktop/ .astro/ src/content/docs/ +src/content/desktop/ public/reference/ public/examples/ diff --git a/docs-site/README.md b/docs-site/README.md index 1938a48a..f5a8bd33 100644 --- a/docs-site/README.md +++ b/docs-site/README.md @@ -1,4 +1,4 @@ -# OpenWorker SDK documentation site +# OpenWorker documentation site Plain Markdown in `docs/harness/` is authoritative and readable on GitHub. `pages.json` chooses the public navigation; `scripts/prepare.mjs` adds site-only @@ -21,6 +21,30 @@ shared custom Astro layout instead of Starlight presentation components. Pagefin indexes the public guides in `pages.json` after the static build; preview and error pages are excluded. The site does not require a private repository to build. +## Desktop App preview + +Desktop user guides live in `docs/desktop/guides/`. `desktop-pages.json` is their +explicit publication manifest. They reuse Studio, with their own navigation, +content directory, output and search index; the normal build remains the SDK. + +```sh +npm run desktop:build +npm run desktop:preview -- --host 127.0.0.1 --port 4330 +# http://127.0.0.1:4330/docs/desktop/ +python3 scripts/verify-built.py dist-desktop /docs/desktop desktop +``` + +The Desktop scripts above use POSIX environment assignment. On other shells, +set `OW_DOCS_PRODUCT=desktop`, then run `npm run prepare-content`, `npx astro build` +and `npx pagefind --site dist-desktop --root-selector "[data-pagefind-body]"`. +Keep that variable set for `npm run preview` too. Build products sequentially; +the generated public asset directory is refreshed for the selected product. + +The initial Desktop pages are a local, noindex preview. SDK design-comparison +routes and source bundles are excluded from the Desktop build. Publication is a +separate step: the existing hosting preparation and router target `/docs/sdk/` +and must not be used to deploy Desktop output without a reviewed hosting change. + ## Language tabs in plain Markdown Wrap alternatives with HTML-comment markers and ordinary headings: diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs index 23550e4f..c8464031 100644 --- a/docs-site/astro.config.mjs +++ b/docs-site/astro.config.mjs @@ -1,8 +1,12 @@ import {defineConfig} from 'astro/config'; import sitemap from '@astrojs/sitemap'; +import {docsProduct} from './product.mjs'; +const product=docsProduct(); export default defineConfig({ site:'https://openworker.com', - base:process.env.OW_DOCS_BASE??'/docs/sdk', + base:product.base, + outDir:product.id==='desktop'?'./dist-desktop':'./dist', + cacheDir:product.id==='desktop'?'./node_modules/.astro-desktop':'./node_modules/.astro', devToolbar:{enabled:false}, integrations:[sitemap({filter:url=>!url.includes('/previews/')})], }); diff --git a/docs-site/desktop-pages.json b/docs-site/desktop-pages.json new file mode 100644 index 00000000..db3009a3 --- /dev/null +++ b/docs-site/desktop-pages.json @@ -0,0 +1,86 @@ +[ + { + "source": "docs/desktop/guides/index.md", + "slug": "index" + }, + { + "source": "docs/desktop/guides/first-task.md", + "slug": "first-task" + }, + { + "source": "docs/desktop/guides/how-it-works.md", + "slug": "how-it-works" + }, + { + "source": "docs/desktop/guides/models.md", + "slug": "models" + }, + { + "source": "docs/desktop/guides/local-models.md", + "slug": "local-models" + }, + { + "source": "docs/desktop/guides/voice.md", + "slug": "voice" + }, + { + "source": "docs/desktop/guides/coworkers.md", + "slug": "coworkers" + }, + { + "source": "docs/desktop/guides/coding.md", + "slug": "coding" + }, + { + "source": "docs/desktop/guides/sessions-files.md", + "slug": "sessions-files" + }, + { + "source": "docs/desktop/guides/connectors.md", + "slug": "connectors" + }, + { + "source": "docs/desktop/guides/skills-memory.md", + "slug": "skills-memory" + }, + { + "source": "docs/desktop/guides/automations.md", + "slug": "automations" + }, + { + "source": "docs/desktop/guides/security.md", + "slug": "security" + }, + { + "source": "docs/desktop/guides/machines.md", + "slug": "machines" + }, + { + "source": "docs/desktop/guides/run-location.md", + "slug": "run-location" + }, + { + "source": "docs/desktop/guides/sandbox.md", + "slug": "sandbox" + }, + { + "source": "docs/desktop/guides/native-sandbox.md", + "slug": "native-sandbox" + }, + { + "source": "docs/desktop/guides/openshell.md", + "slug": "openshell" + }, + { + "source": "docs/desktop/guides/approvals.md", + "slug": "approvals" + }, + { + "source": "docs/desktop/guides/privacy.md", + "slug": "privacy" + }, + { + "source": "docs/desktop/guides/troubleshooting.md", + "slug": "troubleshooting" + } +] diff --git a/docs-site/package.json b/docs-site/package.json index 544effe6..1cfd705d 100644 --- a/docs-site/package.json +++ b/docs-site/package.json @@ -7,6 +7,8 @@ "dev": "npm run prepare-content && astro dev", "build": "npm run prepare-content && astro build && pagefind --site dist --root-selector \"[data-pagefind-body]\"", "preview": "astro preview", + "desktop:build": "OW_DOCS_PRODUCT=desktop npm run prepare-content && OW_DOCS_PRODUCT=desktop astro build && pagefind --site dist-desktop --root-selector \"[data-pagefind-body]\"", + "desktop:preview": "OW_DOCS_PRODUCT=desktop astro preview", "test": "node --test scripts/*.test.mjs" }, "dependencies": { diff --git a/docs-site/product.mjs b/docs-site/product.mjs new file mode 100644 index 00000000..411628e6 --- /dev/null +++ b/docs-site/product.mjs @@ -0,0 +1,21 @@ +import sdkPages from './pages.json' with {type:'json'}; +import desktopPages from './desktop-pages.json' with {type:'json'}; +import {navigation as sdkNavigation} from './src/lib/navigation.mjs'; +import {desktopNavigation} from './src/lib/desktop-navigation.mjs'; + +// An explicit manifest per product keeps private notes and unreviewed pages out +// of both the static output and search. SDK remains the default build target. +export function docsProduct(env=process.env) { + const id=env.OW_DOCS_PRODUCT??'sdk'; + if(!['sdk','desktop'].includes(id))throw Error(`Unknown docs product: ${id}`); + const desktop=id==='desktop'; + return { + id, + label:desktop?'Desktop App':'Harness SDK', + title:desktop?'OpenWorker Desktop':'OpenWorker SDK', + base:env.OW_DOCS_BASE??`/docs/${id}`, + content:desktop?'desktop':'docs', + pages:desktop?desktopPages:sdkPages, + navigation:desktop?desktopNavigation:sdkNavigation, + }; +} diff --git a/docs-site/scripts/prepare.mjs b/docs-site/scripts/prepare.mjs index 937436d1..200a0e2f 100644 --- a/docs-site/scripts/prepare.mjs +++ b/docs-site/scripts/prepare.mjs @@ -4,22 +4,35 @@ import {dirname,resolve,join,posix} from 'node:path'; import {fileURLToPath} from 'node:url'; import {renderCodeTabs} from './code-tabs.mjs'; import {writeSources,renderSourceButton} from './source-examples.mjs'; +import {docsProduct} from '../product.mjs'; const site=resolve(dirname(fileURLToPath(import.meta.url)),'..'),root=resolve(site,'..'); -const pages=JSON.parse(readFileSync(join(site,'pages.json'),'utf8')); -const output=join(site,'src/content/docs'),base=(process.env.OW_DOCS_BASE??'/docs/sdk').replace(/\/$/,''); +const product=docsProduct(),pages=product.pages; +const output=join(site,'src/content',product.content),base=product.base.replace(/\/$/,''); // Remove previously generated reference pages so an incremental build cannot // accidentally republish archived design/specification material. rmSync(join(site,'public/reference'),{recursive:true,force:true}); -const images=new Map(['pdf-notes'].map(name=>[ +const images=product.id==='desktop'?new Map([ + ['docs/desktop/guides/images/notes-to-brief.svg','examples/notes-to-brief.svg'], + ['docs/desktop/samples/meeting-notes.zip','examples/meeting-notes.zip'], +]):new Map(['pdf-notes'].map(name=>[ `docs/harness/guides/images/${name}.jpg`, `examples/${name}.jpg` ])); -images.set('docs/harness/assets/architecture.svg', 'examples/architecture.svg'); -images.set('docs/harness/guides/images/session-tracing.jpg', 'examples/session-tracing.jpg'); +if(product.id==='sdk') { + images.set('docs/harness/assets/architecture.svg', 'examples/architecture.svg'); + images.set('docs/harness/guides/images/session-tracing.jpg', 'examples/session-tracing.jpg'); +} else { + for(const name of ['models','voice','machines','coworkers','sandbox','auto-approve']) + images.set(`docs/desktop/guides/images/${name}.jpg`, `examples/desktop/${name}.jpg`); +} +// This directory is generated. Clear the other product's assets as well so +// switching build targets cannot leak SDK source bundles into Desktop output. +rmSync(join(site,'public/examples'),{recursive:true,force:true}); mkdirSync(join(site,'public/examples'),{recursive:true}); -rmSync(join(site,'public/examples/code-atlas.png'),{force:true}); -rmSync(join(site,'public/examples/pdf-notes.png'),{force:true}); -for(const [source,destination] of images) copyFileSync(join(root,source),join(site,'public',destination)); -writeSources(root,join(site,'public')); +for(const [source,destination] of images) { + mkdirSync(dirname(join(site,'public',destination)),{recursive:true}); + copyFileSync(join(root,source),join(site,'public',destination)); +} +if(product.id==='sdk')writeSources(root,join(site,'public')); const route=new Map(pages.map(p=>[p.source,`${base}/${p.slug==='index'?'':p.slug+'/'}`])); rmSync(output,{recursive:true,force:true});mkdirSync(output,{recursive:true}); for(const page of pages) { @@ -35,4 +48,4 @@ for(const page of pages) { raw=renderSourceButton(renderCodeTabs(raw,page.slug),base); writeFileSync(join(output,page.slug+'.md'),`---\ntitle: ${JSON.stringify(title[1])}\n---\n\n${raw}`); } -console.log(`Prepared ${pages.length} SDK pages from repository Markdown`); +console.log(`Prepared ${pages.length} ${product.label} pages from repository Markdown`); diff --git a/docs-site/scripts/product.test.mjs b/docs-site/scripts/product.test.mjs new file mode 100644 index 00000000..deb84993 --- /dev/null +++ b/docs-site/scripts/product.test.mjs @@ -0,0 +1,39 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import {readFileSync,existsSync} from 'node:fs'; +import {resolve,dirname} from 'node:path'; +import {fileURLToPath} from 'node:url'; +import {docsProduct} from '../product.mjs'; + +const root=resolve(dirname(fileURLToPath(import.meta.url)),'../..'); +test('Desktop and SDK have explicit separate manifests and navigation',()=>{ + const sdk=docsProduct({}),desktop=docsProduct({OW_DOCS_PRODUCT:'desktop'}); + assert.equal(sdk.base,'/docs/sdk'); + assert.equal(desktop.base,'/docs/desktop'); + assert.notEqual(sdk.content,desktop.content); + const required=['index','first-task','how-it-works','models','local-models','voice','coworkers','coding','security','machines','run-location','sandbox','native-sandbox','openshell','approvals','privacy','troubleshooting']; + for(const slug of required)assert.ok(desktop.pages.some(page=>page.slug===slug),slug); + for(const product of [sdk,desktop]) { + const slugs=new Set(product.pages.map(page=>page.slug==='index'?'':page.slug)); + assert.equal(slugs.size,product.pages.length,'Duplicate page routes'); + for(const section of product.navigation)for(const [,slug]of section.links)assert.ok(slugs.has(slug),slug); + for(const page of product.pages) { + assert.ok(page.source.startsWith(`docs/${product.id==='sdk'?'harness':'desktop'}/guides/`)); + assert.ok(existsSync(resolve(root,page.source))); + assert.ok(!/ledger|journal|evidence|\.env/i.test(page.source)); + } + } + assert.equal(docsProduct({OW_DOCS_PRODUCT:'desktop',OW_DOCS_BASE:'/preview/desktop'}).base,'/preview/desktop'); + assert.throws(()=>docsProduct({OW_DOCS_PRODUCT:'unknown'}),/Unknown docs product/); +}); + +test('first-task sample and UI instructions agree with the app source',()=>{ + const read=path=>readFileSync(resolve(root,path),'utf8'); + const ui=JSON.parse(read('surfaces/gui/src/locales/en.json')); + const guide=read('docs/desktop/guides/first-task.md'); + for(const label of [ui.intro.task_folder_title,ui.access.allow_writes,ui.composer.mode.interactive,ui.nav.settings])assert.ok(guide.includes(label),label); + const samples=['01-kickoff.md','02-design-review.md','03-launch-check.md'].map(name=>read(`docs/desktop/samples/meeting-notes/${name}`)).join('\n'); + for(const phrase of ['read-only preview','Priya','Thursday','Sam','Friday','support handoff','not confirmed'])assert.ok(samples.includes(phrase),phrase); + assert.ok(guide.includes('../samples/meeting-notes.zip')); + assert.ok(!/0\.\d+\.\d+|beta\.\d+/i.test(guide),'Keep release numbers out of the walkthrough'); +}); diff --git a/docs-site/scripts/verify-built.py b/docs-site/scripts/verify-built.py index 3a815af9..93208707 100644 --- a/docs-site/scripts/verify-built.py +++ b/docs-site/scripts/verify-built.py @@ -7,7 +7,9 @@ site = Path(__file__).resolve().parent.parent root = site.parent output = Path(sys.argv[1]).resolve() base = sys.argv[2].rstrip('/') -pages = json.loads((site/'pages.json').read_text()) +product = sys.argv[3] if len(sys.argv)>3 else 'sdk' +assert product in ('sdk','desktop'), product +pages = json.loads((site/('desktop-pages.json' if product=='desktop' else 'pages.json')).read_text()) class Page(HTMLParser): def __init__(self, html): super().__init__(); self.ids=set(); self.links=[]; self.sources=[]; self.indexed=False; self.studio=False; self.pres=0 @@ -27,7 +29,7 @@ for p in pages: assert page.studio and page.indexed, file # Source drawer has one extra pre; all Markdown code fences remain present. fences=len(re.findall(r'^```[^\n]*\n[\s\S]*?^```', (root/p['source']).read_text(), re.M)) - assert page.pres==fences+(p['slug'] in ('desktop','server')), (file,page.pres,fences) + assert page.pres==fences+(product=='sdk' and p['slug'] in ('desktop','server')), (file,page.pres,fences) for file,page in parsed.items(): for target in page.links+page.sources: url=urlsplit(target) @@ -42,5 +44,15 @@ for file,page in parsed.items(): assert (output/'pagefind/pagefind.js').exists(), 'Missing search bundle' for name in ['apple','notion']: preview=output/'previews/desktop'/name/'index.html' - assert not Page(preview.read_text()).indexed + if product=='sdk': assert not Page(preview.read_text()).indexed + else: assert not preview.exists(), 'SDK previews must not appear in Desktop output' +if product=='desktop': + from zipfile import ZipFile + with ZipFile(output/'examples/meeting-notes.zip') as archive: + samples=root/'docs/desktop/samples' + expected=sorted(str(path.relative_to(samples)) for path in (samples/'meeting-notes').glob('*.md')) + assert sorted(archive.namelist())==expected, 'Unexpected sample ZIP contents' + for name in expected: assert archive.read(name)==(samples/name).read_bytes(), name + assert not (output/'examples/desktop.json').exists(), 'SDK source bundle in Desktop output' + assert not (output/'examples/web.json').exists(), 'SDK source bundle in Desktop output' print(f'Checked {len(parsed)} Studio guides, code blocks, links, images, anchors and search assets at {base}') diff --git a/docs-site/src/layouts/StudioDocs.astro b/docs-site/src/layouts/StudioDocs.astro index 6694d484..4e379805 100644 --- a/docs-site/src/layouts/StudioDocs.astro +++ b/docs-site/src/layouts/StudioDocs.astro @@ -1,11 +1,12 @@ --- -import {navigation} from '../lib/navigation.mjs'; +import {docsProduct} from '../../product.mjs'; import SourceDrawer from '../components/SourceDrawer.astro'; import '../styles/studio.css'; const {guide,slug='index',notFound=false}=Astro.props; +const product=docsProduct(),navigation=product.navigation,isDesktop=product.id==='desktop'; const base=import.meta.env.BASE_URL.replace(/\/$/,''); const routeSlug=slug==='index'?'':slug; -const sourceTrack=slug==='desktop'?'desktop':slug==='server'?'web':null; +const sourceTrack=isDesktop?null:slug==='desktop'?'desktop':slug==='server'?'web':null; const group=navigation.find(group=>group.links.some(([,link])=>link===routeSlug)); const label=group?.links.find(([,link])=>link===routeSlug)?.[0]??guide.title; const sequence=navigation.flatMap(group=>group.links); @@ -17,47 +18,47 @@ const description=guide.subtitle.replace(/<[^>]+>/g,'').trim(); - {guide.title} | OpenWorker SDK + {guide.title===product.title?guide.title:`${guide.title} | ${product.title}`} - {notFound?:} + {notFound||isDesktop?:} - +
- OpenWorkerDeveloper - + OpenWorker{isDesktop?'Desktop App':'Developer'} +
-
DocumentationHarness SDK
+
Documentation{isDesktop?'Building an app? Explore the SDK ↗':'Harness SDK'}
- +

{guide.title}

{guide.subtitle&&
} {sourceTrack&&
Build with AI
} - {slug==='index'&&} - + {slug==='index'&&(isDesktop?:)} + {!isDesktop&&}
{guide.headings.length>0&&}
- +
{sourceTrack&&} - -
-

Search guides, examples and deployment instructions.

+ +
+

{isDesktop?'Search Desktop guides and walkthroughs.':'Search guides, examples and deployment instructions.'}