@_linked/cli 1.8.1 → 1.9.0

package/defaults/app-with-backend/gitignore.template

@@ -1,25 +0,0 @@
-node_modules
-build
-mrgit.json
-public/bundles
-data/uploads
-data/metadata
-data/sessions
-linked.backend.datasets.json
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/sdks
-!.yarn/versions
-packages/**/dist
-packages/**/lib
-packages/**/.yarn/*
-!packages/**/.yarn/patches
-!packages/**/.yarn/plugins
-!packages/**/.yarn/releases
-!packages/**/.yarn/sdks
-!packages/**/.yarn/versions
-.idea
-android/app/build
-ios/App/App/public

package/defaults/app-with-backend/linked.backend.datasets.example.json

@@ -1,17 +0,0 @@
-{
-  "_note": "Backend datasets config. Copy this file to linked.backend.datasets.json (gitignored) and replace placeholders with literal values, OR set the env vars referenced via ${VAR}. The ${VAR:-default} form falls back to the literal after :- when the env var is unset. Each entry has two keys: `store` (an npm import path string identifying the IDataset class) and `config` (a single JSON object passed verbatim to `new StoreClass(config)` — its fields are whatever that class's constructor expects).",
-
-  "datasets": {
-    "appData": {
-      "store": "@_linked/fuseki/shapes/FusekiStore",
-      "config": {
-        "endpoint": "${FUSEKI_BASE_URL:-http://localhost:3030}/${FUSEKI_DATASET:-${hyphen_name}-main}",
-        "credentials": {
-          "type":     "basic",
-          "username": "${FUSEKI_USER:-admin}",
-          "password": "${FUSEKI_PASSWORD:-admin}"
-        }
-      }
-    }
-  }
-}

package/defaults/app-with-backend/linked.backend.storage.ts

@@ -1,35 +0,0 @@
-// Backend storage for ${name}.
-//
-// Reads linked.backend.datasets.json, dynamically imports each alias's
-// store class via its npm path, and instantiates with the entry's `config`
-// verbatim. See the mirror at src/linked.frontend.storage.ts.
-import datasetsConfig from './linked.backend.datasets.json' with { type: 'json' };
-import { parseDatasetsConfig } from '@_linked/core/utils/parseDatasetsConfig';
-import { loadStores } from '@_linked/core/utils/loadStores';
-import { LinkedStorage } from '@_linked/core/utils/LinkedStorage';
-import { LinkedFileStorage } from '@_linked/core/utils/LinkedFileStorage';
-import type { FusekiStore } from '@_linked/fuseki/shapes/FusekiStore';
-import { LocalFileStore } from '@_linked/server/shapes/filestores/LocalFileStore';
-
-// Resolve ${VAR} placeholders against the runtime environment, then
-// instantiate each store class declared in the JSON.
-const config = parseDatasetsConfig(datasetsConfig, process.env);
-const stores = await loadStores(config);
-
-// Auto-create the dataset on first boot.
-const appData = stores.appData as FusekiStore;
-appData.ensureDatasetExists().catch((err) =>
-  console.warn('dataset ensure failed:', err),
-);
-
-// Shape → alias. Single alias → default for every shape. For multi-alias
-// add per-shape pins, e.g.:
-//   import { Person } from '@_linked/schema/shapes/Person';
-//   LinkedStorage.setDatasetForShapes(stores.appData, [Person]);
-LinkedStorage.setDefaultDataset(appData);
-
-// File storage (binary assets). Separate from RDF dataset routing.
-const fileStore = new LocalFileStore(
-  (process.env.NODE_ENV || 'development') + '-files',
-);
-LinkedFileStorage.setDefaultDataset(fileStore);

package/defaults/app-with-backend/linked.config.js

@@ -1,5 +0,0 @@
-export default {
-  cssMode: 'tailwind',
-  cacheWebpack: true,
-  analyse: false,
-};

package/defaults/app-with-backend/package.json

@@ -1,70 +0,0 @@
-{
-  "name": "${hyphen_name}",
-  "displayName": "${name}",
-  "description": "",
-  "version": "0.1.0",
-  "private": true,
-  "type": "module",
-  "linkedApp": true,
-  "author": {
-    "name": "",
-    "url": "",
-    "email": ""
-  },
-  "engines": {
-    "node": ">=20.6.0"
-  },
-  "main": "scripts/start-server.js",
-  "license": "MIT",
-  "scripts": {
-    "start": "linked start --env development",
-    "build": "linked build-app --env production",
-    "server:prod": "linked start --env production",
-    "lint": "eslint \"src/**/*.{js,jsx,ts,tsx}\"",
-    "lint:fix": "npm run lint -- --fix",
-    "prettier": "prettier \"src/**/*.{js,jsx,ts,tsx,css,scss}\" --check",
-    "prettier:fix": "npm run prettier -- --write",
-    "format": "npm run prettier:fix && npm run lint:fix"
-  },
-  "keywords": [
-    "linked",
-    "linked code",
-    "linked data",
-    "structured data",
-    "RDF",
-    "semantic web",
-    "web3"
-  ],
-  "dependencies": {
-    "@_linked/core": "^2.6",
-    "@_linked/server": "^2.0",
-    "@_linked/server-utils": "^1.0.6",
-    "@_linked/schema": "^1.0.6",
-    "@_linked/fuseki": "^2.0.1",
-    "@_linked/primitives": "^1.0.6",
-    "@_linked/react": "^1.3",
-    "react": "^18.2",
-    "react-dom": "^18.2",
-    "react-error-boundary": "^3.1.3",
-    "react-router-dom": "^6.3.0"
-  },
-  "devDependencies": {
-    "@_linked/cli": "^1.4",
-    "@types/node": "^20.12.7",
-    "@types/react": "^18.0.17",
-    "@types/react-dom": "^18.0.6",
-    "@typescript-eslint/eslint-plugin": "latest",
-    "@typescript-eslint/parser": "latest",
-    "env-cmd": "^10.1.0",
-    "eslint": "latest",
-    "eslint-config-prettier": "^8.9.0",
-    "eslint-import-resolver-typescript": "^3.5.5",
-    "eslint-plugin-prettier": "^5.0.0",
-    "eslint-plugin-react": "latest",
-    "eslint-plugin-react-hooks": "latest",
-    "nodemon": "^2.0.22",
-    "pm2": "^5.3.0",
-    "typescript-plugin-css-modules": "^5.1.0",
-    "which": "^3.0.1"
-  }
-}

package/defaults/app-with-backend/pm2-staging.config.js

@@ -1,12 +0,0 @@
-module.exports = {
-  apps: [
-    {
-      name: '${hyphen_name}-staging',
-      script: 'yarn run server:staging',
-      time: true,
-      log_date_format: 'DD-MM-YYYY HH:mm Z',
-      out_file: './data/out.log',
-      error_file: './data/error.log',
-    },
-  ],
-};

package/defaults/app-with-backend/pm2.config.js

@@ -1,12 +0,0 @@
-module.exports = {
-  apps: [
-    {
-      name: '${hyphen_name}',
-      script: 'yarn run server:prod',
-      time: true,
-      log_date_format: 'DD-MM-YYYY HH:mm Z',
-      out_file: "./data/out.log",
-      error_file: "./data/error.log",
-    }
-  ],
-};

package/defaults/app-with-backend/readme.md

@@ -1,93 +0,0 @@
-# ${name}
-
-A standalone [Linked](https://linked.cm) app generated with `@_linked/cli`. Requires **Node ≥ 20.6**.
-
-## What is Linked
-
-Linked is a TypeScript framework for building apps on top of a graph database (RDF / SPARQL). You write your domain as **shape classes**, query them with a **typed DSL**, and render with **linked React components** that subscribe to the query results.
-
-```ts
-// 1. A shape — domain class + SHACL metadata, generated from TypeScript decorators
-@linkedShape
-export class Person extends Shape {
-  static targetClass = schema.Person;
-
-  @literalProperty({ path: schema.givenName })  givenName: string;
-  @literalProperty({ path: schema.familyName }) familyName: string;
-}
-
-// 2. A query — TypeScript-embedded, type-inferred, executed against any IDataset
-const people = await Person.select((p) => [p.givenName, p.familyName]);
-
-// 3. A linked component — re-renders when its query result changes
-const PersonCard = linkedComponent(
-  Person.select((p) => [p.givenName, p.familyName]),
-  ({ givenName, familyName }) => <span>{givenName} {familyName}</span>,
-);
-```
-
-The home page in this app demonstrates the full chain end-to-end with `@_linked/schema`'s shipped `Person` shape.
-
-- **[@_linked/core](https://github.com/linked-cm/core)** — query DSL, Shape classes, storage routing.
-- **[@_linked/react](https://github.com/Semantu/linked-react)** — `linkedComponent`, `linkedSetComponent`.
-
-## Install + run
-
-With npm:
-
-```bash
-npm install
-npm start
-```
-
-Or with yarn:
-
-```bash
-yarn install
-yarn start
-```
-
-The home page demonstrates the `@_linked` query DSL with a small Person CRUD — see `src/components/PersonOverview.tsx` and `src/components/PersonPreview.tsx`.
-
-> If you scaffolded this app **inside an existing Yarn-workspace monorepo** (e.g. `packages/` of another repo), use `yarn install` — `npm install` walks up to the workspace root and may hit peer-dep conflicts there. Outside a workspace, either tool works.
-
-## Storage
-
-This app talks to an Apache Jena Fuseki SPARQL endpoint. Start a local Fuseki container:
-
-```bash
-docker run -d --rm -p 3030:3030 --name fuseki stain/jena-fuseki
-```
-
-The app auto-creates its dataset on first boot.
-
-**Storage config lives in three files**, per the spec in [`@_linked/cli` docs](https://www.npmjs.com/package/@_linked/cli):
-
-| File | Purpose |
-|---|---|
-| `linked.backend.datasets.json` | Backend Layer 2 — alias → store class + config. Gitignored. Copy of `linked.backend.datasets.example.json`. |
-| `linked.backend.storage.ts` | Backend Layer 1 — shape → alias routing. Parses the JSON, instantiates stores via `loadStores`, calls `LinkedStorage.setDefaultDataset(...)` / `setDatasetForShapes(...)`. |
-| `src/linked.frontend.{storage.ts,datasets.json}` | Frontend mirror — same JSON shape, public values only; storage TS imports store classes explicitly and constructs one per alias. |
-
-Defaults shipped:
-
-- `FUSEKI_BASE_URL` — `http://localhost:3030`
-- `FUSEKI_DATASET`  — `${hyphen_name}-main`
-- `FUSEKI_USER` / `FUSEKI_PASSWORD` — `admin` / `admin` (matches the `stain/jena-fuseki` Docker image default)
-- `FUSEKI_DB_TYPE`  — `tdb2` (persistent). Set to `mem` for in-memory.
-
-All of these are referenced as `${VAR:-default}` placeholders in `linked.backend.datasets.json`, so you can either edit the JSON directly or set env vars.
-
-## Build for production
-
-```bash
-npm run build
-npm run server:prod
-```
-
-## Learn more
-
-- [@_linked/core](https://www.npmjs.com/package/@_linked/core) — query DSL, Shape classes, storage routing. See `parseDatasetsConfig` + `loadStores` for the dataset-config helpers.
-- [@_linked/react](https://www.npmjs.com/package/@_linked/react) — `linkedComponent`, `linkedSetComponent`.
-- [@_linked/schema](https://www.npmjs.com/package/@_linked/schema) — shipped Shape classes (Person, Place, Organization, …).
-- [@_linked/css](https://www.npmjs.com/package/@_linked/css) — design tokens, Tailwind v4 theme primitives, `@utility` mixins. See `src/theme.css` for the wiring.

package/defaults/app-with-backend/src/App.module.css

@@ -1,83 +0,0 @@
-@import '@_linked/css/package.css';
-
-:global(body) {
-  font-family: var(--font-sans);
-  background: var(--bg-page);
-  color: var(--color-gray-900);
-  margin: 0;
-  overflow-x: hidden;
-}
-
-/* Animated background: soft radial-gradient "blobs" drifting and pulsing
-   underneath the content. Brand-colored via @_linked/css tokens — recolors
-   automatically when --color-primary-* / --color-secondary-* change in theme.css. */
-:global(body)::before {
-  content: '';
-  position: fixed;
-  inset: 0;
-  z-index: -1;
-  pointer-events: none;
-  background:
-    radial-gradient(
-      circle at 18% 22%,
-      var(--color-primary-300) 0%,
-      transparent 38%
-    ),
-    radial-gradient(
-      circle at 82% 76%,
-      var(--color-secondary-300) 0%,
-      transparent 42%
-    ),
-    radial-gradient(
-      circle at 55% 58%,
-      var(--color-tertiary-200) 0%,
-      transparent 50%
-    );
-  opacity: 0.35;
-  filter: blur(40px);
-  animation: drift 22s ease-in-out infinite;
-}
-
-@keyframes drift {
-  0%,
-  100% {
-    transform: translate3d(0, 0, 0) scale(1);
-  }
-  33% {
-    transform: translate3d(-3%, 2%, 0) scale(1.05);
-  }
-  66% {
-    transform: translate3d(3%, -2%, 0) scale(0.97);
-  }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  :global(body)::before {
-    animation: none;
-  }
-}
-
-.App {
-  min-height: 100vh;
-  position: relative;
-}
-
-:global(h1) {
-  font-size: 1.75rem;
-  font-weight: 600;
-  margin: 0;
-}
-
-:global(h2) {
-  font-size: 1.25rem;
-  font-weight: 600;
-  margin: 0 0 --spacing(3);
-}
-
-:global(a) {
-  color: var(--color-primary-600);
-}
-
-:global(a:hover) {
-  color: var(--color-primary-700);
-}

package/defaults/app-with-backend/src/App.tsx

@@ -1,30 +0,0 @@
-import './theme.css'; //needs to be the first import before importing other components
-import React, { Suspense } from 'react';
-import { ErrorBoundary } from 'react-error-boundary';
-import { Spinner } from './components/Spinner';
-import { Error } from './components/Error';
-import { AppRoot } from '@_linked/server-utils/components/AppRoot';
-import { Head } from '@_linked/server-utils/components/Head';
-import { Body } from '@_linked/server-utils/components/Body';
-import AppRoutes, { ROUTES } from './routes';
-import style from './App.module.css'; //import any .module.css file like this and access the classnames from the style object
-
-// To add sign-in to this app, install `@_linked/auth`, wrap <AppRoutes/>
-// in <ProvideAuth>, and uncomment the `requireAuth` line in routes.tsx.
-
-export default function App() {
-  return (
-    <AppRoot>
-      <Head>
-        {/*  Add tags to html <head> here, for example, a font <link href='https://fonts.someapi.com/...' />*/}
-      </Head>
-      <Body routes={ROUTES} pageStyles={style} className={style.App}>
-        <Suspense fallback={<Spinner />}>
-          <ErrorBoundary FallbackComponent={Error}>
-            <AppRoutes />
-          </ErrorBoundary>
-        </Suspense>
-      </Body>
-    </AppRoot>
-  );
-}

package/defaults/app-with-backend/src/backend.ts

@@ -1,9 +0,0 @@
-//import all ShapeProviders here or define a generic BackendProvider, see https://linked.cm
-
-import { BackendProvider } from '@_linked/server-utils/utils/BackendProvider';
-
-export class Backend extends BackendProvider {
-  constructor(server, linkedServer) {
-    super(server, linkedServer);
-  }
-}

package/defaults/app-with-backend/src/components/Error.module.css

@@ -1,9 +0,0 @@
-.error {
-  color: white;
-  margin: 2rem;
-
-  pre {
-    white-space: pre-wrap;
-    padding: 1rem;
-  }
-}

package/defaults/app-with-backend/src/components/Error.tsx

@@ -1,11 +0,0 @@
-import React from 'react';
-import style from './Error.module.css';
-
-export function Error({ error }) {
-  return (
-    <div className={style.error}>
-      <h1>Application Error</h1>
-      <pre>{error.stack}</pre>
-    </div>
-  );
-}

package/defaults/app-with-backend/src/components/PersonOverview.module.css

@@ -1,100 +0,0 @@
-@import '@_linked/css/package.css';
-
-.Root {
-  background: var(--bg-card);
-  border-radius: var(--radius-card);
-  box-shadow: var(--shadow-card);
-  padding: --spacing(6);
-}
-
-.Intro {
-  color: var(--color-gray-600);
-  font-size: 0.9rem;
-  line-height: 1.5;
-  margin: 0 0 --spacing(5);
-}
-
-.Intro code {
-  background: var(--bg-section);
-  padding: 0 --spacing(1);
-  border-radius: var(--radius-element);
-  font-family: var(--font-mono);
-  font-size: 0.85em;
-}
-
-.Empty {
-  color: var(--color-gray-500);
-  font-style: italic;
-  padding: --spacing(4) 0;
-  margin: 0;
-}
-
-.Loading {
-  color: var(--color-gray-500);
-  padding: --spacing(4) 0;
-  margin: 0;
-}
-
-.List {
-  list-style: none;
-  padding: 0;
-  margin: 0 0 --spacing(5);
-}
-
-.List > li {
-  padding: --spacing(3) 0;
-  border-bottom: 1px solid var(--color-gray-200);
-}
-
-.List > li:first-child {
-  padding-top: 0;
-}
-
-.List > li:last-child {
-  border-bottom: none;
-}
-
-.Form {
-  display: flex;
-  gap: --spacing(2);
-  flex-wrap: wrap;
-  padding-top: --spacing(4);
-  border-top: 1px solid var(--color-gray-200);
-}
-
-.Form input {
-  flex: 1 1 140px;
-  padding: --spacing(2) --spacing(3);
-  border: 1px solid var(--color-gray-300);
-  border-radius: var(--radius-element);
-  background: var(--bg-card);
-  color: var(--color-gray-900);
-  font: inherit;
-}
-
-.Form input:focus {
-  outline: none;
-  border-color: var(--color-primary-500);
-  box-shadow: 0 0 0 2px var(--color-primary-200);
-}
-
-.Form button {
-  padding: --spacing(2) --spacing(5);
-  background: var(--color-primary-500);
-  color: var(--color-white);
-  border: none;
-  border-radius: var(--radius-element);
-  font: inherit;
-  font-weight: 500;
-  cursor: pointer;
-  transition: background 120ms ease;
-}
-
-.Form button:hover:not(:disabled) {
-  background: var(--color-primary-600);
-}
-
-.Form button:disabled {
-  opacity: 0.6;
-  cursor: not-allowed;
-}

package/defaults/app-with-backend/src/components/PersonOverview.tsx

@@ -1,97 +0,0 @@
-// Example PersonOverview — demonstrates @_linked/react's data binding:
-// linkedSetComponent for the list (auto-runs the query, injects results and
-// an injected _refresh); linkedComponent for each row (see PersonPreview).
-// After Person.create the form calls _refresh() to re-run the list query.
-//
-// Replace or extend this with your own shapes (see https://linked.cm).
-import React, { useCallback, useRef, useState } from 'react';
-import { linkedSetComponent } from '@_linked/react';
-import { Person } from '@_linked/schema/shapes/Person';
-import { PersonPreview } from './PersonPreview';
-import { PersonListRefreshProvider } from './PersonOverviewContext';
-import style from './PersonOverview.module.css';
-
-const PersonList = linkedSetComponent(
-  Person.select((p) => [p.givenName, p.familyName]),
-  ({ linkedData = [], _refresh, refreshRef }: any) => {
-    // Forward the list's _refresh up via a ref so the sibling form +
-    // child rows can trigger a re-fetch through context.
-    if (refreshRef) {
-      refreshRef.current = _refresh;
-    }
-
-    if (linkedData.length === 0) {
-      return (
-        <p className={style.Empty}>No people yet. Add one below.</p>
-      );
-    }
-
-    return (
-      <ul className={style.List} data-testid="person-list">
-        {linkedData.map((p: { id: string }) => (
-          <li key={p.id}>
-            <PersonPreview of={{ id: p.id }} />
-          </li>
-        ))}
-      </ul>
-    );
-  },
-);
-
-function PersonAddForm({ onAdded }: { onAdded: () => void }) {
-  const [given, setGiven] = useState('');
-  const [family, setFamily] = useState('');
-  const [busy, setBusy] = useState(false);
-
-  async function submit(e: React.FormEvent) {
-    e.preventDefault();
-    if (!given && !family) return;
-    setBusy(true);
-    try {
-      await Person.create({ givenName: given, familyName: family });
-      setGiven('');
-      setFamily('');
-      onAdded();
-    } finally {
-      setBusy(false);
-    }
-  }
-
-  return (
-    <form className={style.Form} onSubmit={submit}>
-      <input
-        value={given}
-        placeholder="First name"
-        onChange={(e) => setGiven(e.target.value)}
-      />
-      <input
-        value={family}
-        placeholder="Last name"
-        onChange={(e) => setFamily(e.target.value)}
-      />
-      <button type="submit" disabled={busy}>
-        Add
-      </button>
-    </form>
-  );
-}
-
-export function PersonOverview() {
-  const refreshRef = useRef<() => void>(() => {});
-  const refresh = useCallback(() => refreshRef.current(), []);
-
-  return (
-    <PersonListRefreshProvider value={refresh}>
-      <div className={style.Root} data-testid="person-overview">
-        <h2>People</h2>
-        <p className={style.Intro}>
-          Example code using the <code>@_linked</code> query DSL against
-          your local Fuseki dataset. Edit{' '}
-          <code>src/components/PersonOverview.tsx</code> to extend it.
-        </p>
-        <PersonList refreshRef={refreshRef} />
-        <PersonAddForm onAdded={refresh} />
-      </div>
-    </PersonListRefreshProvider>
-  );
-}

package/defaults/app-with-backend/src/components/PersonOverviewContext.tsx

@@ -1,12 +0,0 @@
-// Small context that lets PersonPreview rows trigger a list refresh on
-// their parent PersonOverview without prop-drilling through the
-// linkedSetComponent's wrapped renderer.
-import React, { useContext } from 'react';
-
-const PersonListRefreshContext = React.createContext<() => void>(() => {});
-
-export const PersonListRefreshProvider = PersonListRefreshContext.Provider;
-
-export function usePersonListRefresh(): () => void {
-  return useContext(PersonListRefreshContext);
-}