From 522720da6abfda1b2ba6b17de420053dcc9e8182 Mon Sep 17 00:00:00 2001 From: Carl Niklas Rydberg Date: Sat, 7 Feb 2026 20:27:12 +0100 Subject: [PATCH] Add index-init aware daemon startup helper and docs updates --- .gitignore | 4 ++ README.md | 16 ++++--- config/env.example | 8 +++- docs/v2-app-developer-guide.md | 5 ++- scripts/dev_start_daemon.sh | 78 ++++++++++++++++++++++++++++++++++ scripts/ingest_example.sh | 6 +-- src/config.sh | 2 +- tests/integration_v2.sh | 4 +- 8 files changed, 110 insertions(+), 13 deletions(-) create mode 100755 scripts/dev_start_daemon.sh diff --git a/.gitignore b/.gitignore index 6271d23..7dca44f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,11 @@ # Local daemon/store runtime state .amduat-asl/ +.amduat-asl-*/ amduatd.sock +.amduatd-*.sock .cursor +.amduatd-*.pid +.amduatd-*.log # Local configuration overrides config/env.local diff --git a/README.md b/README.md index dfd6edb..5fc727b 100644 --- a/README.md +++ b/README.md @@ -16,19 +16,25 @@ Starter project scaffold for building an app against `amduatd` v2. cp config/env.example config/env.local ``` -2. Run startup checks against a running `amduatd` socket: +2. Start a local daemon: + +```sh +./scripts/dev_start_daemon.sh +``` + +3. Run startup checks against the daemon socket: ```sh ./scripts/bootstrap_check.sh ``` -3. Run sample idempotent batch ingest: +4. Run sample idempotent batch ingest: ```sh ./scripts/ingest_example.sh ``` -4. Run sample changes sync loop: +5. Run sample changes sync loop: ```sh ./scripts/sync_loop.sh @@ -40,9 +46,9 @@ Use the integrated v2 app flow wrapper: ```sh ./scripts/v2_app.sh startup-check -./scripts/v2_app.sh ingest '{"idempotency_key":"k1","mode":"continue_on_error","nodes":[{"name":"doc:1"}]}' +./scripts/v2_app.sh ingest '{"idempotency_key":"k1","mode":"continue_on_error","nodes":[{"name":"doc-1"}]}' ./scripts/v2_app.sh sync-once -./scripts/v2_app.sh retrieve 'doc:1' 'ms.within_domain' +./scripts/v2_app.sh retrieve 'doc-1' 'ms.within_domain' ./scripts/v2_app.sh tombstone '' ``` diff --git a/config/env.example b/config/env.example index 2c745e8..087ad20 100644 --- a/config/env.example +++ b/config/env.example @@ -1,8 +1,14 @@ # Copy to config/env.local and edit as needed -SOCK="../amduatd.sock" +SOCK="amduatd.sock" BASE="http://localhost" SPACE="app1" +# Optional daemon startup defaults (used by scripts/dev_start_daemon.sh) +STORE_ROOT=".amduat-asl" +STORE_BACKEND="index" +# AMDUATD_BIN="/path/to/amduatd" +# ASL_BIN="/path/to/amduat-asl" + # Incremental sync configuration SYNC_LIMIT="200" SYNC_WAIT_MS="15000" diff --git a/docs/v2-app-developer-guide.md b/docs/v2-app-developer-guide.md index ebbf9a7..40afb12 100644 --- a/docs/v2-app-developer-guide.md +++ b/docs/v2-app-developer-guide.md @@ -14,10 +14,13 @@ For machine-readable contracts, see `registry/amduatd-api-contract.v2.json`. Minimal local run: ```sh -./vendor/amduat/build/amduat-asl init --root .amduat-asl +./vendor/amduat/build/amduat-asl index init --root .amduat-asl ./build/amduatd --root .amduat-asl --sock amduatd.sock --store-backend index ``` +If you run with `--store-backend index`, initialize the root with `index init` +instead of `init`. + ## 2) Request Conventions - Use `X-Amduat-Space: ` for app isolation. diff --git a/scripts/dev_start_daemon.sh b/scripts/dev_start_daemon.sh new file mode 100755 index 0000000..7300724 --- /dev/null +++ b/scripts/dev_start_daemon.sh @@ -0,0 +1,78 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +ENV_FILE="${ROOT_DIR}/config/env.local" +if [[ ! -f "${ENV_FILE}" ]]; then + ENV_FILE="${ROOT_DIR}/config/env.example" +fi +# shellcheck source=/dev/null +source "${ENV_FILE}" + +STORE_ROOT="${STORE_ROOT:-${ROOT_DIR}/.amduat-asl}" +STORE_BACKEND="${STORE_BACKEND:-index}" +SPACE="${SPACE:-app1}" +SOCK="${SOCK:-${ROOT_DIR}/amduatd.sock}" +if [[ "${STORE_ROOT}" != /* ]]; then + STORE_ROOT="${ROOT_DIR}/${STORE_ROOT}" +fi +if [[ "${SOCK}" != /* ]]; then + SOCK="${ROOT_DIR}/${SOCK}" +fi + +# Try common local build paths first, then PATH. +AMDUATD_BIN="${AMDUATD_BIN:-}" +if [[ -z "${AMDUATD_BIN}" ]]; then + for cand in \ + "${ROOT_DIR}/vendor/amduat-api/build/amduatd" \ + "${ROOT_DIR}/vendor/amduat-api/build-asan/amduatd"; do + if [[ -x "${cand}" ]]; then + AMDUATD_BIN="${cand}" + break + fi + done + if [[ -z "${AMDUATD_BIN}" ]] && command -v amduatd >/dev/null 2>&1; then + AMDUATD_BIN="$(command -v amduatd)" + fi +fi + +ASL_BIN="${ASL_BIN:-}" +if [[ -z "${ASL_BIN}" ]]; then + for cand in \ + "${ROOT_DIR}/vendor/amduat-api/vendor/amduat/build/amduat-asl" \ + "${ROOT_DIR}/vendor/amduat-api/build/vendor/amduat/amduat-asl"; do + if [[ -x "${cand}" ]]; then + ASL_BIN="${cand}" + break + fi + done + if [[ -z "${ASL_BIN}" ]] && command -v amduat-asl >/dev/null 2>&1; then + ASL_BIN="$(command -v amduat-asl)" + fi +fi + +if [[ -z "${AMDUATD_BIN}" || ! -x "${AMDUATD_BIN}" ]]; then + echo "missing amduatd binary; set AMDUATD_BIN" >&2 + exit 1 +fi +if [[ -z "${ASL_BIN}" || ! -x "${ASL_BIN}" ]]; then + echo "missing amduat-asl binary; set ASL_BIN" >&2 + exit 1 +fi + +mkdir -p "${STORE_ROOT}" + +if [[ "${STORE_BACKEND}" == "index" ]]; then + if ! "${ASL_BIN}" index state --root "${STORE_ROOT}" >/dev/null 2>&1; then + echo "initializing index-backed ASL store at ${STORE_ROOT}" >&2 + "${ASL_BIN}" index init --root "${STORE_ROOT}" + fi +else + if ! "${ASL_BIN}" log inspect --root "${STORE_ROOT}" >/dev/null 2>&1; then + echo "initializing ASL store at ${STORE_ROOT}" >&2 + "${ASL_BIN}" init --root "${STORE_ROOT}" + fi +fi + +echo "starting amduatd: root=${STORE_ROOT} sock=${SOCK} backend=${STORE_BACKEND} space=${SPACE}" >&2 +exec "${AMDUATD_BIN}" --root "${STORE_ROOT}" --sock "${SOCK}" --store-backend "${STORE_BACKEND}" --space "${SPACE}" diff --git a/scripts/ingest_example.sh b/scripts/ingest_example.sh index 7aa9ad5..f48533f 100755 --- a/scripts/ingest_example.sh +++ b/scripts/ingest_example.sh @@ -8,12 +8,12 @@ source "${ROOT_DIR}/src/client.sh" payload='{ "idempotency_key":"app1-seed-0001", "mode":"continue_on_error", - "nodes":[{"name":"doc:1"},{"name":"topic:alpha"}], + "nodes":[{"name":"doc-1"},{"name":"topic-alpha"}], "edges":[ { - "subject":"doc:1", + "subject":"doc-1", "predicate":"ms.within_domain", - "object":"topic:alpha", + "object":"topic-alpha", "provenance":{ "source_uri":"urn:app:seed", "extractor":"app-loader", diff --git a/src/config.sh b/src/config.sh index 7c3a915..ad91922 100755 --- a/src/config.sh +++ b/src/config.sh @@ -35,7 +35,7 @@ amduat_config_load() { if [[ -n "${override_connect_timeout}" ]]; then CURL_CONNECT_TIMEOUT_SECONDS="${override_connect_timeout}"; fi if [[ -n "${override_max_time}" ]]; then CURL_MAX_TIME_SECONDS="${override_max_time}"; fi - SOCK="${SOCK:-../amduatd.sock}" + SOCK="${SOCK:-amduatd.sock}" BASE="${BASE:-http://localhost}" SPACE="${SPACE:-app1}" diff --git a/tests/integration_v2.sh b/tests/integration_v2.sh index 421f25a..c14902c 100755 --- a/tests/integration_v2.sh +++ b/tests/integration_v2.sh @@ -36,8 +36,8 @@ assert_contains "${startup_out}" '"ok"' run_id="$(date +%s)" trace_id="trace-it-${run_id}" idempotency_key="it-seed-${run_id}" -doc_name="doc:it${run_id}" -topic_name="topic:italpha${run_id}" +doc_name="doc-it${run_id}" +topic_name="topic-italpha${run_id}" payload="$(cat <