docs: document public alpha setup
This commit is contained in:
parent
ca5290015a
commit
581e6b27d8
165
README.md
165
README.md
|
|
@ -1,80 +1,151 @@
|
||||||
# Verstak Desktop
|
# Verstak
|
||||||
|
|
||||||
Verstak is a local-first desktop workspace for files, notes, browser captures,
|
Verstak is a local-first workspace for files, notes, browser captures,
|
||||||
activity and work journal entries. This repository contains the Go/Wails desktop
|
activity and work-journal entries. This repository is the desktop application:
|
||||||
host and UI shell; user-facing functions are delivered by official plugins.
|
the Go/Wails host and UI shell that loads plugins from a `plugins/` directory
|
||||||
|
next to its executable.
|
||||||
|
|
||||||
> **Alpha software.** Use a disposable vault while evaluating it. APIs, storage
|
> **Alpha software.** Use a disposable vault while evaluating it. APIs, storage
|
||||||
> formats and packaging can change before the first stable release.
|
> formats and packaging can change before the first stable release.
|
||||||
|
|
||||||
## What the alpha does
|
|
||||||
|
|
||||||
- keeps each workspace's identity independent of its current directory name;
|
|
||||||
- keeps browser captures in a reviewable Inbox, with archive and restore rather
|
|
||||||
than a destructive “remove from inbox” action;
|
|
||||||
- records local file/note activity and, after review, turns it into journal
|
|
||||||
entries without creating a workspace automatically;
|
|
||||||
- accepts optional browser domain-time batches. The browser extension is
|
|
||||||
opt-in: it sends only normalized domain names and bounded durations, never
|
|
||||||
URLs, page titles, page contents, keystrokes or navigation history;
|
|
||||||
- runs official plugins from a `plugins/` directory next to the executable.
|
|
||||||
|
|
||||||
## Components
|
## Components
|
||||||
|
|
||||||
Clone these repositories as siblings when building a complete local setup:
|
The public alpha is split into small repositories. Keep their `main` branches
|
||||||
|
in the same release line when building from source.
|
||||||
|
|
||||||
| Repository | Purpose |
|
| Component | Repository | What it is for |
|
||||||
| --- | --- |
|
| --- | --- | --- |
|
||||||
| `verstak-desktop` | desktop host and UI shell |
|
| Desktop | [mirivlad/verstak](https://github.com/mirivlad/verstak) | This application: vault UI, local host and plugin runtime. |
|
||||||
| `verstak-official-plugins` | Files, Notes, Browser Inbox, Activity, Journal and other official plugins |
|
| Official plugins | [mirivlad/verstak-official-plugins](https://github.com/mirivlad/verstak-official-plugins) | Files, Notes, Browser Inbox, Activity, Journal, Sync, Todo and other first-party plugins. |
|
||||||
| `verstak-browser-extension` | Chromium/Firefox capture and optional domain-activity extension |
|
| Browser extension | [mirivlad/verstak-browser-extension](https://github.com/mirivlad/verstak-browser-extension) | Manual browser captures and opt-in domain-time activity. |
|
||||||
| `verstak-sdk` | plugin manifest schema and TypeScript API |
|
| Sync server | [mirivlad/verstak-sync-server](https://github.com/mirivlad/verstak-sync-server) | Optional self-hosted synchronization between devices. |
|
||||||
|
| Plugin SDK | [mirivlad/verstak-sdk](https://github.com/mirivlad/verstak-sdk) | TypeScript API, JSON schemas and contract tests for plugin authors. |
|
||||||
|
| Architecture documentation | [mirivlad/verstak-docs](https://github.com/mirivlad/verstak-docs) | Product, platform and plugin-system design documents. |
|
||||||
|
|
||||||
## Build from source (Linux)
|
No server account or browser extension is needed for a local desktop vault.
|
||||||
|
|
||||||
Requirements: Go, Node.js with npm, Python 3, the [Wails v2 build
|
## Build the desktop and official plugins
|
||||||
prerequisites](https://wails.io/docs/gettingstarted/installation/), and the
|
|
||||||
WebKitGTK development package for your distribution.
|
The current release scripts target Linux. Install Go 1.24+, Node.js 20+ with
|
||||||
|
npm, Python 3, the [Wails v2 build
|
||||||
|
prerequisites](https://wails.io/docs/gettingstarted/installation/), and your
|
||||||
|
distribution's WebKitGTK development package.
|
||||||
|
|
||||||
|
Clone the repositories as siblings. The directory names below are intentional:
|
||||||
|
the desktop helper finds the official-plugin checkout at
|
||||||
|
`../verstak-official-plugins`.
|
||||||
|
|
||||||
|
```text
|
||||||
|
verstak-workspace/
|
||||||
|
├── verstak/
|
||||||
|
├── verstak-sdk/
|
||||||
|
├── verstak-official-plugins/
|
||||||
|
└── verstak-browser-extension/ # optional for browser integration
|
||||||
|
```
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://git.mirv.top/verstak/verstak-sdk.git
|
git clone https://github.com/mirivlad/verstak.git verstak
|
||||||
git clone https://git.mirv.top/verstak/verstak-official-plugins.git
|
git clone https://github.com/mirivlad/verstak-sdk.git verstak-sdk
|
||||||
git clone https://git.mirv.top/verstak/verstak-desktop.git
|
git clone https://github.com/mirivlad/verstak-official-plugins.git verstak-official-plugins
|
||||||
git clone https://git.mirv.top/verstak/verstak-browser-extension.git
|
git clone https://github.com/mirivlad/verstak-browser-extension.git verstak-browser-extension
|
||||||
|
|
||||||
cd verstak-sdk && ./scripts/build.sh
|
cd verstak-sdk && ./scripts/build.sh
|
||||||
cd ../verstak-official-plugins && ./scripts/build.sh
|
cd ../verstak-official-plugins && ./scripts/build.sh
|
||||||
cd ../verstak-desktop
|
cd ../verstak
|
||||||
./scripts/install-dev-plugins.sh
|
./scripts/install-dev-plugins.sh
|
||||||
./scripts/build.sh
|
./scripts/build.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
The Linux executable is placed in `build/bin/`. Start it with `--debug` to
|
`install-dev-plugins.sh` copies the packages from
|
||||||
display internal plugin-provider IDs and write diagnostic logs.
|
`../verstak-official-plugins/dist/` into this repository's `plugins/`
|
||||||
|
directory. `build.sh` then copies them to `build/bin/plugins/`, beside the
|
||||||
|
desktop executable:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./build/bin/verstak-desktop
|
||||||
|
```
|
||||||
|
|
||||||
|
For a manually assembled installation, place each unpacked plugin directory
|
||||||
|
directly in `plugins/` beside `verstak-desktop`; for example,
|
||||||
|
`plugins/browser-inbox/plugin.json`. Do not put the release archive itself in
|
||||||
|
that directory. The desktop release archive already includes its matching
|
||||||
|
`plugins/` directory.
|
||||||
|
|
||||||
|
Start with `--debug` to show internal plugin-provider identifiers and write
|
||||||
|
diagnostic logs:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./build/bin/verstak-desktop --debug
|
||||||
|
```
|
||||||
|
|
||||||
|
## First local vault
|
||||||
|
|
||||||
|
1. Launch the desktop application and choose or create a writable vault folder.
|
||||||
|
Verstak stores its local metadata in that vault; do not point it at a
|
||||||
|
read-only directory.
|
||||||
|
2. Create a Дело (workspace) in the Files plugin before assigning captures or
|
||||||
|
activity to it.
|
||||||
|
3. Open Notes, Files, Activity and Journal as needed. Activity candidates are
|
||||||
|
only suggestions: a Journal entry and a new Дело are always created by the
|
||||||
|
user.
|
||||||
|
|
||||||
|
## Browser extension
|
||||||
|
|
||||||
|
The extension is optional. Build it locally with `npm ci && npm test && npm run
|
||||||
|
build` in `verstak-browser-extension/`, then load `dist/chromium` as an
|
||||||
|
unpacked Chromium extension or `dist/firefox` temporarily in Firefox. A signed
|
||||||
|
Firefox XPI is available from the [extension's GitHub
|
||||||
|
Releases](https://github.com/mirivlad/verstak-browser-extension/releases).
|
||||||
|
|
||||||
|
To connect it to the desktop application:
|
||||||
|
|
||||||
|
1. Ensure the `browser-inbox` plugin is installed and open its settings in
|
||||||
|
Verstak.
|
||||||
|
2. Copy the displayed Receiver URL and Pairing Token.
|
||||||
|
3. Paste both values into the extension's settings and save.
|
||||||
|
4. Use a manual Send Page, selection, link or file action to create a Browser
|
||||||
|
Inbox capture.
|
||||||
|
|
||||||
|
Passive domain activity is disabled by default. When the user explicitly turns
|
||||||
|
it on, the extension sends only bounded time totals by normalized domain. It
|
||||||
|
does not send URLs, page titles, page contents, keystrokes, navigation history
|
||||||
|
or inactive-tab time. The extension settings provide a domain exclusion list.
|
||||||
|
|
||||||
|
## Optional sync server
|
||||||
|
|
||||||
|
The sync server is self-hosted and is not required for local use. Build and
|
||||||
|
start a development instance from a sibling checkout:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/mirivlad/verstak-sync-server.git verstak-sync-server
|
||||||
|
cd verstak-sync-server
|
||||||
|
./scripts/build.sh
|
||||||
|
./build/bin/verstak-sync-server --port 47732 --data ./server-data \
|
||||||
|
--admin-user admin --admin-pass 'choose-a-strong-password'
|
||||||
|
```
|
||||||
|
|
||||||
|
For a second device or a production host, follow the deployment, HTTPS and
|
||||||
|
backup guidance in the [sync server
|
||||||
|
README](https://github.com/mirivlad/verstak-sync-server#readme). In the desktop
|
||||||
|
application, open the Sync plugin, enter the server URL and user credentials,
|
||||||
|
test the connection, then select **Connect**. Each vault is paired separately.
|
||||||
|
|
||||||
## Release artifacts
|
## Release artifacts
|
||||||
|
|
||||||
Maintainers can create a Linux desktop tarball after the sibling repositories
|
Maintainers can produce a self-contained Linux desktop archive after the SDK
|
||||||
above have been built:
|
and official plugins have been built:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd verstak-desktop
|
cd verstak
|
||||||
./scripts/release.sh v0.1.0-alpha.1
|
./scripts/release.sh v0.1.0-alpha.1
|
||||||
```
|
```
|
||||||
|
|
||||||
It writes `release/verstak-desktop-linux-amd64-<version>.tar.gz` and a matching
|
It writes `release/verstak-desktop-linux-amd64-<version>.tar.gz` and a matching
|
||||||
`SHA256SUMS` file. The archive is self-contained: unpack it and run the
|
`SHA256SUMS` file. Unpack the archive and run the included executable; its
|
||||||
included executable. Browser and SDK packages have their own release scripts
|
matching plugins are already in the archive. The browser extension, SDK,
|
||||||
|
official plugins and sync server have their own build or release instructions
|
||||||
in their repositories.
|
in their repositories.
|
||||||
|
|
||||||
## Privacy and activity tracking
|
|
||||||
|
|
||||||
The extension's passive domain tracker is disabled by default. Enabling it
|
|
||||||
requires an explicit choice in the extension and lets the user maintain a
|
|
||||||
domain exclusion list. Manual page, selection and link captures are separate
|
|
||||||
actions; they enter Browser Inbox and never create a workspace or journal
|
|
||||||
entry by themselves.
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
Copyright © 2026 Verstak contributors. Licensed under
|
Copyright © 2026 Verstak contributors. Licensed under
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
{
|
{
|
||||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||||
"$id": "https://git.mirv.top/verstak/verstak-sdk/schemas/hostname-normalization-v1.json",
|
"$id": "https://raw.githubusercontent.com/mirivlad/verstak-sdk/main/schemas/hostname-normalization-v1.json",
|
||||||
"title": "Verstak canonical hostname normalization v1 test vectors",
|
"title": "Verstak canonical hostname normalization v1 test vectors",
|
||||||
"description": "Canonical hostnames are lowercase ASCII A-labels without a port or trailing DNS dot. Bare hostnames accept DNS names, IPv4, bracketed IPv6, localhost, and internal single-label names. URL inputs accept only HTTP(S). Invalid or excessively long input normalizes to an empty string.",
|
"description": "Canonical hostnames are lowercase ASCII A-labels without a port or trailing DNS dot. Bare hostnames accept DNS names, IPv4, bracketed IPv6, localhost, and internal single-label names. URL inputs accept only HTTP(S). Invalid or excessively long input normalizes to an empty string.",
|
||||||
"version": 1,
|
"version": 1,
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue