fix: carry a value the grammar cannot model through as source text

occ runs inside the service container, so a value main cannot read is a
brick with no way to reach the command that would remove it. Recovery
needs filesystem access to config.php, which a StartOS user does not have.

Two such values are reachable from documented occ invocations, because
var_export writes them as expressions: PHP_INT_MIN, which
`config:system:set --type=integer` saturates any out-of-range negative
onto, and a NUL byte. Rather than teach the grammar those two literals,
Value falls back to capturing the source text of anything it cannot model
and the serializer re-emits it byte for byte.

The fallback needs a terminator lookahead to be reachable at all: Number
matches the leading -9223372036854775807 of PHP_INT_MIN, and PEG does not
retry an alternative once the enclosing sequence fails.

Bounded so malformed input still fails loudly rather than merging the
entries around it: Raw stops at a newline, since var_export never spreads
a scalar expression over two lines, and a bare positional entry may not be
raw. Verified against PHP 8.4 that a missing comma, a missing =>, an
unterminated string, an unterminated comment and a truncated file all
still throw.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: MattDHill

AGENTS.md

@@ -32,6 +32,8 @@ verified, tried, and decided belongs in the commit message and the PR body.
 - **Long-running `occ` work must be queued, never run inline in an action handler** — it would block past the action timeout. Adding one means matching entries in `OCC_ARGS`, `TASK_NOTICE`, and a conditional health check, all keyed off `ACTION_IDS`.
 - **`startos/fileModels/php-parser.js` is generated — edit `php.pegjs` and run `npm run regen-parser`.** Nothing in the build reads the grammar, so a grammar edit that skips the regeneration passes `check` and `build` and ships the old parser.
 - **`config.php` keeps keys the shape does not model.** The SDK patches `z.object` to be loose, so validation keeps unknown keys and the serializer writes them back — a key a user or a Nextcloud app adds survives. Model a key when the package needs to read or default it, not to preserve it. Do not make the validator strict: `instanceid`, `passwordsalt` and `secret` are unmodelled. Dropping `secret` or `passwordsalt` takes Nextcloud offline with a 503 `config variable is not configured in the config.php file` page, and dropping `instanceid` makes Nextcloud mint a new one, orphaning `appdata_<instanceid>`.
-- **The `config.php` grammar reads literals, not expressions, and numbers go through a JavaScript double.** Comments do parse, and they have to: Nextcloud 34 prepends a banner comment between `<?php` and `$CONFIG` on every config write, so rejecting one meant the service could not start. `var_export` renders a NUL byte and `PHP_INT_MIN` as expressions (`'a' . "\0" . 'b'`, `-9223372036854775807-1`), and neither parses, so `main` will not start until the value is gone — `occ config:system:set <key> --type=integer` saturates any out-of-range negative onto `PHP_INT_MIN`. An integer above 2^53 loses precision on the next write, and a whole-valued float comes back an integer.
+- **A value the `config.php` grammar cannot model is carried through as source text — never narrow `Raw` into a hard failure.** `occ` runs inside the service container, so a value that stops the read is a brick with no way to reach the command that would remove it. Malformed input must still fail loudly, which is what bounds `Raw` to a single line: `var_export` never spreads a scalar expression over two, so a run that reaches a newline is a broken file rather than an unmodelled value. A carried-through value is `{ __raw: <source> }`, so a PHP array whose only key is `__raw` and whose value is a string is indistinguishable from one.
+- **Comments have to parse.** Nextcloud 34 prepends a banner comment between `<?php` and `$CONFIG` on every config write.
+- **`config.php` numbers go through a JavaScript double.** An integer above 2^53 loses precision on the next write, and a whole-valued float comes back an integer.
 - **The File Browser mount's `idmap` (uid 1000 → `www-data` 33) is what makes the integration work at all**, and it needs StartOS 0.4.0-beta.10+. Files other services drop into File Browser's volume under a different uid surface as `nobody` until those services idmap their own mount to 1000 too.
 - **Adding an external-storage source is a registry edit in `startos/externalStorage.ts` plus a typed mount.** File Browser is the shared hub most services route through, so a direct source is worth adding only for a service whose files live browsably on its own volume.

README.md

@@ -75,7 +75,7 @@ Two models, and only one of them is upstream's.
 | `config/config.php` | `nextcloud` | PHP    | Yes — `FileHelper.raw`  | Every start, and the Configure action |
 | `store.json`        | `main`      | JSON   | Yes — `FileHelper.json` | Install, and several actions          |
 
-`config.php` is PHP, not a config format any parser handles, so the model carries a **PEG grammar** (`php.pegjs`) to read it and a serializer to write it back. **A key outside the shape survives**: the SDK's `z.object` is loose, so `instanceid`, `passwordsalt`, `secret` and anything a Nextcloud app or an admin adds are read, kept and written back. A key the shape models keeps its value too, unless the shape rejects it or pins it to a literal — the enforced list below. Numbers pass through a JavaScript double, so an integer above 2^53 loses precision and a whole-valued float comes back an integer.
+`config.php` is PHP, not a config format any parser handles, so the model carries a **PEG grammar** (`php.pegjs`) to read it and a serializer to write it back. **A key outside the shape survives**: the SDK's `z.object` is loose, so `instanceid`, `passwordsalt`, `secret` and anything a Nextcloud app or an admin adds are read, kept and written back. A key the shape models keeps its value too, unless the shape rejects it or pins it to a literal — the enforced list below. A value written in a form the grammar does not model is left exactly as it was found, so a setting the package cannot interpret can never stop it from starting. Numbers pass through a JavaScript double, so an integer above 2^53 loses precision and a whole-valued float comes back an integer.
 
 **Enforced** — re-asserted whenever the package writes: the database connection (type, name, host, port, user, table prefix), the Valkey memcache trio and its connection, `datadirectory`, `trusted_proxies` (the service bridge's subnet), `filelocking.enabled`, `check_for_working_wellknown_setup`, `overwriteprotocol` (held unset, so a value set by hand is removed), and the three in the table below.
 

startos/fileModels/config.php.ts

@@ -75,28 +75,34 @@ function toSingleQuotedLiteral(str: string) {
   return "'" + str.replace(/[\\']/g, (c) => '\\' + c) + "'"
 }
 
+// The parser's marker for a value it could not model, holding that value's
+// source text.
+const isRaw = (v: object): v is { __raw: string } =>
+  Object.keys(v).length === 1 &&
+  typeof (v as { __raw?: unknown }).__raw === 'string'
+
 function toPhpString(value: unknown, indent = 0): string {
   switch (typeof value) {
     case 'object':
-      return value == null
-        ? 'null'
-        : `array (\n${
-            Array.isArray(value)
-              ? value
-                  .filter((x) => x !== undefined)
-                  .reduce(
-                    (acc, x, idx) =>
-                      `${acc}${'  '.repeat(indent + 1)}${idx} => ${toPhpString(x, indent + 1)},\n`,
-                    '',
-                  )
-              : Object.entries(value)
-                  .filter(([k, v]) => k !== undefined && v !== undefined)
-                  .reduce(
-                    (acc, [key, value]) =>
-                      `${acc}${'  '.repeat(indent + 1)}${toPhpString(key)} => ${toPhpString(value, indent + 1)},\n`,
-                    '',
-                  )
-          }${'  '.repeat(indent)})`
+      if (value === null) return 'null'
+      if (isRaw(value)) return value.__raw
+      return `array (\n${
+        Array.isArray(value)
+          ? value
+              .filter((x) => x !== undefined)
+              .reduce(
+                (acc, x, idx) =>
+                  `${acc}${'  '.repeat(indent + 1)}${idx} => ${toPhpString(x, indent + 1)},\n`,
+                '',
+              )
+          : Object.entries(value)
+              .filter(([k, v]) => k !== undefined && v !== undefined)
+              .reduce(
+                (acc, [key, value]) =>
+                  `${acc}${'  '.repeat(indent + 1)}${toPhpString(key)} => ${toPhpString(value, indent + 1)},\n`,
+                '',
+              )
+      }${'  '.repeat(indent)})`
     case 'string':
       return toSingleQuotedLiteral(value)
     case 'number':
@@ -132,7 +138,7 @@ export const configPhp = FileHelper.raw<z.infer<typeof shape>>(
       // A `$CONFIG` that is not an array would merge down to the shape's
       // defaults, and the write that follows would drop `secret`, `instanceid`
       // and `dbpassword`. Refuse it while the file is still intact.
-      if (typeof parsed !== 'object' || parsed === null)
+      if (typeof parsed !== 'object' || parsed === null || isRaw(parsed))
         throw new Error('$CONFIG is not an array')
       return parsed
     } catch (e) {