Barkly Website Automation — Functional Requirements

FR-01 — Source-controlled deployment

The system SHALL deploy the website from the committed source repository.

The deployment system SHALL:

identify the commit being deployed

retrieve the requested Git revision

preserve the deployed commit identifier

report the deployed revision

fail if the requested revision cannot be retrieved

FR-02 — Website build

The deployment system SHALL build the Astro website before publishing it.

The system SHALL:

install or verify required dependencies

execute the project's defined build command

capture build output

detect build failures

prevent publication when the build fails

Requirement: A failed build SHALL NOT replace the currently deployed website.

FR-03 — Deployment staging

The system SHALL build the website in a staging location before replacing the live website.

repository

↓

source

↓

build

↓

staging/dist

↓

validation

↓

live website

The live website SHALL only be modified after a successful build and validation.

Barkly QA

FR-04 — Recursive page discovery

Barkly QA SHALL recursively discover website pages beginning from the configured site root.

Example:

├── about

├── architecture

├── charter

├── cyn-x

├── docs

├── funding

├── laas

├── projects

└── standard

The system SHALL discover additional pages through valid webpage links rather than requiring a manually maintained page list.

FR-05 — Navigation link validation

Barkly QA SHALL inspect actual webpage navigation links.

The system SHALL validate:

links.

The system SHALL NOT treat the following as webpage navigation:

JavaScript resources

CSS resources

images

Astro development resources

Vite resources

source files

FR-06 — Broken-link detection

Barkly QA SHALL identify links that cannot successfully resolve.

The system SHALL report:

source page

target URL

HTTP status or connection error

failure type

Example:

BROKEN LINK

Target: /old-project

Found on: /projects

Status: HTTP 404

FR-07 — Internal URL normalization

Barkly QA SHALL resolve relative links against the configured website root.

The system SHALL support:

/about

/docs

/projects

without requiring a repository-specific deployment prefix such as:

/BarklyLabs-webpage/

The crawler SHALL support configurable deployment roots so the same QA system can operate locally and on the production VPS.

FR-08 — Recursive crawl protection

Barkly QA SHALL prevent infinite crawling.

The system SHALL:

maintain a visited-page set

avoid repeatedly crawling the same normalized URL

remove URL fragments when determining page identity

support a configurable maximum page count

FR-09 — QA failure status

Barkly QA SHALL return a non-zero process exit status when required validation fails.

This SHALL allow deployment automation to use QA as a deployment gate.

Example:

Build

↓

PASS → Deploy

FAIL → Stop

Barkly Deployment + QA Integration

FR-10 — Pre-publication QA

The deployment system SHALL execute required QA checks before replacing the live website.

A deployment SHALL NOT be considered successful if required QA checks fail.

FR-11 — Deployment report

Each deployment SHALL produce a machine-readable and human-readable result containing at minimum:

Commit

Build status

Pages discovered

Links checked

Broken links

QA status

Deployment status

Timestamp

Example:

BARKLY DEPLOYMENT

Commit: a83f91c

Build: PASS

QA:

Pages: 17

Links: 64

Broken: 0

Status: PASS

Deployment: PASS

Published revision: a83f91c

FR-12 — Failure preservation

If any required deployment stage fails:

Git

↓

Build

↓

Publish

the currently live version SHALL remain available.

This gives you the really important safety property:

A broken commit cannot automatically destroy the working website.

FR-13 — Deployment logging

The system SHALL maintain deployment history containing:

timestamp

commit

build result

QA result

deployment result

failure information where applicable

That gives Barkly a little history of what version was actually live.

FR-14 — Dry-run mode

Both Barkly Deploy and Barkly QA SHOULD support a dry-run mode.

Example:

python barkly_deploy.py --dry-run

The system SHALL report the actions it would perform without modifying the live deployment.

FR-15 — Local development support

The system SHALL support testing against a local Astro development or preview server.

Example:

localhost:4321

without confusing Astro/Vite development resources with website pages.

FR-16 — Production support

The same QA system SHALL support the production website hosted at the VPS domain.

Therefore:

LOCAL

localhost:4321/

↓

PRODUCTION

barkly-labs.org/

↓

should use the same underlying QA logic.

The really important architectural requirement

I'd make this an explicit Barkly principle:

Deployment automation SHALL treat build, validation, and publication as separate stages.

So you're not building one giant scary script.

Barkly Deploy

│

├── Source

│

├── Build

│

├── QA

│

├── Publish

│