Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/*
* config_json_like.h — Structure-preserving JSON/JSONC/JSON5 config edits.
*/
#ifndef CBM_CONFIG_JSON_LIKE_H
#define CBM_CONFIG_JSON_LIKE_H
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
/* Editors only rewrite missing paths or regular, single-link config files.
* POSIX symlinks and Windows reparse points fail closed. Existing POSIX
* owner/group/mode metadata is retained across the atomic replacement. The
* destination and synced temporary file are identity/byte revalidated
* immediately before publication. Portable platforms without a path-identity
* CAS still have a narrow interval between final verification and replacement.
*
* Insert or replace entry_key inside the object at object_path.
* entry_json must contain exactly one strict JSON value.
* Returns 0 on success and -1 on invalid input or an I/O error. */
int cbm_json_like_upsert_entry(const char *file_path, const char *const *object_path,
size_t path_len, const char *entry_key, const char *entry_json);
/* Safely read one regular, single-link document. Returns 0 with malloc-owned
* content, 1 when missing, and -1 for unsafe filesystem state or I/O failure. */
int cbm_json_like_read_document(const char *file_path, char **content_out, size_t *length_out);
/* Read one uniquely named value from object_path without mutating the file.
* On success, value_json_out receives a malloc-owned, NUL-terminated exact
* JSON/JSONC/JSON5 source slice and value_length_out its byte length. Returns
* 1 when the file, path, or entry is missing and -1 for ambiguity, malformed
* input, unsafe filesystem state, or I/O failure. */
int cbm_json_like_get_raw_entry(const char *file_path, const char *const *object_path,
size_t path_len, const char *entry_key, char **value_json_out,
size_t *value_length_out);
/* Exact object-entry schema matching on a caller-owned document snapshot.
* Every object member must match one field exactly once; unknown and duplicate
* members produce CBM_JSON_LIKE_OBJECT_MISMATCH. STRING fields may require an
* exact decoded value or capture their decoded value for caller validation.
*
* This API intentionally accepts document bytes rather than a path so callers
* can validate the same snapshot supplied to an *_if_unchanged mutation. */
typedef enum {
CBM_JSON_LIKE_VALUE_STRING,
CBM_JSON_LIKE_VALUE_EMPTY_ARRAY,
CBM_JSON_LIKE_VALUE_SINGLE_STRING_ARRAY,
/* An exact bare token (true/false/null/a number) matched byte-for-byte
* against expected_string. Requires expected_string and may not be
* combined with CBM_JSON_LIKE_FIELD_CAPTURE_STRING — a fixed token has
* nothing meaningful to capture for the caller. */
CBM_JSON_LIKE_VALUE_LITERAL,
} cbm_json_like_value_shape_t;
enum {
CBM_JSON_LIKE_FIELD_REQUIRED = 1U << 0U,
CBM_JSON_LIKE_FIELD_CAPTURE_STRING = 1U << 1U,
};
typedef struct {
const char *key;
cbm_json_like_value_shape_t shape;
const char *expected_string;
unsigned flags;
} cbm_json_like_object_field_t;
enum {
CBM_JSON_LIKE_OBJECT_MATCH = 0,
CBM_JSON_LIKE_OBJECT_MISSING = 1,
CBM_JSON_LIKE_OBJECT_MISMATCH = 2,
/* Every field we own is present and matches, but the entry carries
* ADDITIONAL keys we do not write. The entry is recognisably ours; it has
* simply been annotated by the client or the user. Callers must NOT rewrite
* such an entry — the editor replaces an entry wholesale, so rewriting
* would silently drop those keys. Treat it as already-satisfied instead. */
CBM_JSON_LIKE_OBJECT_MATCH_WITH_EXTRAS = 3,
};
/* captured_string_out receives malloc-owned decoded content only on MATCH.
* Returns one of CBM_JSON_LIKE_OBJECT_* or -1 for malformed input. */
int cbm_json_like_match_object_entry(const char *document, size_t document_length,
const char *const *object_path, size_t path_len,
const char *entry_key,
const cbm_json_like_object_field_t *fields, size_t field_count,
char **captured_string_out);
/* Conditional variants used when a caller must semantically inspect an exact
* snapshot before writing. expected_content == NULL means the file was
* missing. A changed document is rejected without mutation. */
int cbm_json_like_upsert_entry_if_unchanged(const char *file_path, const char *const *object_path,
size_t path_len, const char *entry_key,
const char *entry_json, const char *expected_content,
size_t expected_length);
/* Replace ONE member's value inside the entry object at object_path/entry_key,
* preserving every other byte of the document (comments, ordering, and any
* keys the client added around it). The field-merge primitive for repairing an
* annotated entry (#1630): replacing the whole entry would drop the client's
* keys. raw_value must be a single complete JSON value; the field must exist
* exactly once. Same expected-content contract as the _if_unchanged editors. */
int cbm_json_like_replace_field_raw_if_unchanged(const char *file_path,
const char *const *object_path, size_t path_len,
const char *entry_key, const char *field_key,
const char *raw_value,
const char *expected_content,
size_t expected_length);
/* Remove entry_key from the object at object_path. A missing path or entry is
* a successful no-op. Returns 0 on success and -1 on invalid input or I/O. */
int cbm_json_like_remove_entry(const char *file_path, const char *const *object_path,
size_t path_len, const char *entry_key);
int cbm_json_like_remove_entry_if_unchanged(const char *file_path, const char *const *object_path,
size_t path_len, const char *entry_key,
const char *expected_content, size_t expected_length);
/* Add string_value once to the array named array_key in the object at
* object_path. Missing objects and the array are created. The raw string is
* JSON-escaped; a pre-existing exact string is a no-op. */
int cbm_json_like_add_unique_string_at_path(const char *file_path, const char *const *object_path,
size_t path_len, const char *array_key,
const char *string_value);
/* Remove the exact string_value from the array at object_path/array_key.
* Missing files, paths, arrays, and strings are successful no-ops. */
int cbm_json_like_remove_string_at_path(const char *file_path, const char *const *object_path,
size_t path_len, const char *array_key,
const char *string_value);
/* Read a string from the object at object_path. On success, value_out receives
* a malloc-owned decoded UTF-8 string. Returns 0 when found, 1 when the file,
* path, or key is missing, and -1 for invalid input, ambiguity, a non-string
* value, unsafe filesystem state, or I/O failure. */
int cbm_json_like_get_string_at_path(const char *file_path, const char *const *object_path,
size_t path_len, const char *string_key, char **value_out);
/* Top-level convenience wrapper for cbm_json_like_add_unique_string_at_path. */
int cbm_json_like_add_unique_string(const char *file_path, const char *array_key,
const char *string_value);
/* Top-level convenience wrapper for cbm_json_like_remove_string_at_path. */
int cbm_json_like_remove_string(const char *file_path, const char *array_key,
const char *string_value);
#ifdef CBM_JSON_LIKE_ENABLE_TEST_API
/* Deterministic concurrency seam for the standalone editor tests. The hook is
* invoked after the replacement has been synced but before the stale-snapshot
* check. Production callers must not enable this API. */
typedef void (*cbm_json_like_precommit_test_hook_t)(const char *file_path, void *context);
void cbm_json_like_set_precommit_hook_for_testing(cbm_json_like_precommit_test_hook_t hook,
void *context);
/* Invoked after the first stale-snapshot check. The editor performs a final
* destination and temporary-file identity check after the hook and
* immediately before publication. */
void cbm_json_like_set_prepublish_hook_for_testing(cbm_json_like_precommit_test_hook_t hook,
void *context);
#endif
#ifdef __cplusplus
}
#endif
#endif /* CBM_CONFIG_JSON_LIKE_H */