mirror of
https://github.com/casjaysdevdocker/super-productivity
synced 2026-09-04 03:03:49 -04:00
📝 Update project spec and documentation 📝
- AI.md
This commit is contained in:
casjay
@@ -30,6 +30,7 @@ This file defines the standards that procedure enforces.
|
||||
| 6 | README.md standard layout |
|
||||
| 7 | CI/CD workflows |
|
||||
| 8 | Verification & commit |
|
||||
| 9 | Examples from real repos |
|
||||
|
||||
---
|
||||
|
||||
@@ -695,3 +696,134 @@ gitcommit --dir "$(git rev-parse --show-toplevel)" all
|
||||
|
||||
`git commit` / `git push` directly are forbidden. Never commit with a failing syntax
|
||||
gate.
|
||||
|
||||
## Project Memory (.claude/memory/)
|
||||
|
||||
Durable, repo-specific knowledge discovered during work on this image — a template
|
||||
quirk, a base-image gotcha, a decision on why something deviates from the generated
|
||||
default — belongs in `.claude/memory/`, not only in a commit message or chat. Committed
|
||||
to the repo, not gitignored. One markdown file per topic, YAML frontmatter (`name`,
|
||||
`description`, `type: project`), indexed by `.claude/memory/MEMORY.md`, read on demand.
|
||||
Same credential-masking rule as everywhere else — never store secrets. `~/.claude/**`
|
||||
(global) stays read-only, deployed only via `claudemgr/config`'s `install.sh`;
|
||||
`.claude/memory/` here is read/write in this repo directly.
|
||||
|
||||
---
|
||||
|
||||
# PART 9: EXAMPLES FROM REAL REPOS
|
||||
|
||||
Real excerpts from live `casjaysdevdocker` repos, showing how the conventions look
|
||||
in practice. Use these as reference patterns — do not copy them verbatim into other
|
||||
repos; adapt names, paths, and versions.
|
||||
|
||||
## 9.1 — App-install `05-custom.sh` (from `casjaysdevdocker/gitea`)
|
||||
|
||||
App repos always own a non-stub `05-custom.sh` — it is where the application binary
|
||||
is installed. The gitea repo (100 lines) shows the canonical version-resolution and
|
||||
download pattern:
|
||||
|
||||
```bash
|
||||
# Set bash options
|
||||
set -o pipefail
|
||||
[ "$DEBUGGER" = "on" ] && echo "Enabling debugging" && set -x$DEBUGGER_OPTIONS
|
||||
# - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
# Set env variables
|
||||
exitCode=0
|
||||
apk add --no-cache ca-certificates 2>/dev/null || true
|
||||
update-ca-certificates 2>/dev/null || true
|
||||
GITEA_VERSION="${GITEA_VERSION:-latest}"
|
||||
GITEA_BIN_FILE="/usr/local/bin/gitea"
|
||||
ARCH="$(uname -m | tr '[:upper]' '[:lower]')"
|
||||
case "$ARCH" in x86_64) ARCH="amd64" ;; aarch64) ARCH="arm64" ;; *) echo "$ARCH is not supported by this script" >&2 && exit 1 ;; esac
|
||||
# Pinned fallback used when gitea.com is unreachable from the build host
|
||||
ACT_RUNNER_FALLBACK_VERSION="${ACT_RUNNER_FALLBACK_VERSION:-v1.0.8}"
|
||||
# Fetch latest version tag from the renamed repo — 30s connect timeout
|
||||
ACT_VERSIONS="$(curl -q --connect-timeout 30 --max-time 45 -LSsf \
|
||||
'https://gitea.com/api/v1/repos/gitea/runner/releases' \
|
||||
-H 'accept: application/json' 2>/dev/null | jq -r '.[].tag_name' | sort -Vr | head -n1)"
|
||||
# Fall back to pinned version if API is unreachable
|
||||
[ -z "$ACT_VERSIONS" ] && ACT_VERSIONS="$ACT_RUNNER_FALLBACK_VERSION"
|
||||
if [ -z "$GITEA_VERSION" ] || [ "$GITEA_VERSION" = "latest" ]; then
|
||||
_latest_url="$(curl -4sfL -o /dev/null -w '%{url_effective}' https://github.com/go-gitea/gitea/releases/latest 2>/dev/null)"
|
||||
GITEA_VERSION="$(printf '%s\n' "$_latest_url" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')"
|
||||
fi
|
||||
GITEA_URL="https://github.com/go-gitea/gitea/releases/download/v${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-${ARCH}"
|
||||
```
|
||||
|
||||
Patterns to note:
|
||||
|
||||
- Version defaults to `latest` but resolves to a concrete number at build time via
|
||||
the upstream API, with a pinned fallback for offline/rate-limited builds
|
||||
- Arch mapping (`x86_64→amd64`, `aarch64→arm64`) with a hard error for anything else
|
||||
- Bounded curl (`--connect-timeout`/`--max-time`), never open-ended
|
||||
- Downloads land in `/usr/local/bin`, are chmodded, and verified before exit 0
|
||||
|
||||
## 9.2 — init.d service script config block (from `casjaysdevdocker/gitea` `08-gitea.sh`)
|
||||
|
||||
One init.d script per service, generated by `gen-script` and then configured by
|
||||
editing ONLY the variable block — the function bodies below it are template code.
|
||||
The configured block from `08-gitea.sh`:
|
||||
|
||||
```bash
|
||||
SERVICE_NAME="gitea"
|
||||
# set data directory
|
||||
DATA_DIR="/data/gitea"
|
||||
# set config directory
|
||||
CONF_DIR="/config/gitea"
|
||||
# set the containers etc directory
|
||||
ETC_DIR="/etc/gitea"
|
||||
# set the temp dir
|
||||
TMP_DIR="/tmp/gitea"
|
||||
# set scripts pid dir
|
||||
RUN_DIR="/run/gitea"
|
||||
# set log directory
|
||||
LOG_DIR="/data/logs/gitea"
|
||||
# Set the working dir
|
||||
WORK_DIR="/data/gitea"
|
||||
# port which service is listening on
|
||||
SERVICE_PORT="80"
|
||||
# gitea must run as git user, not root
|
||||
RUNAS_USER="git"
|
||||
# execute command as another user
|
||||
SERVICE_USER="git"
|
||||
# Set the service group
|
||||
SERVICE_GROUP="git"
|
||||
# execute command variables - keep single quotes variables will be expanded later
|
||||
# command to execute
|
||||
EXEC_CMD_BIN='gitea'
|
||||
# command arguments
|
||||
EXEC_CMD_ARGS='web '
|
||||
# command arguments
|
||||
EXEC_CMD_ARGS+='--port $SERVICE_PORT --config $CONF_DIR/app.ini '
|
||||
```
|
||||
|
||||
Patterns to note:
|
||||
|
||||
- Dir vars all derive from `$SERVICE_NAME` (`/data/{svc}`, `/config/{svc}`,
|
||||
`/run/{svc}`, `/data/logs/{svc}`)
|
||||
- `EXEC_CMD_BIN`/`EXEC_CMD_ARGS` stay single-quoted — template code expands them
|
||||
later, after ports and paths are finalized
|
||||
- Multi-word args are built up with `EXEC_CMD_ARGS+=`, one concern per line
|
||||
|
||||
## 9.3 — Customizing behavior via `*_local()` hooks (from `08-gitea.sh`)
|
||||
|
||||
Template functions (`__pre_execute`, `__update_conf_files`, …) each end by calling
|
||||
an optional `*_local()` hook. Repo-specific behavior goes in the hook, never inside
|
||||
the template function body:
|
||||
|
||||
```bash
|
||||
# function to run before executing
|
||||
__pre_execute() {
|
||||
local exitCode=0
|
||||
...
|
||||
# allow custom functions
|
||||
if builtin type -t __pre_execute_local | grep -q 'function'; then __pre_execute_local; fi
|
||||
return $exitCode
|
||||
}
|
||||
```
|
||||
|
||||
The stubs (`__pre_execute_local() { true; }` etc.) live near the bottom of the
|
||||
script — replace a stub's body to customize; regeneration then only requires
|
||||
re-applying the variable block and the non-stub hooks. Multi-service apps ship one
|
||||
script per service with two-digit ordering (`05-dockerd.sh`, `08-gitea.sh`,
|
||||
`zz-act_runner.sh` for run-last).
|
||||
|
||||
Reference in New Issue
Block a user