# Developer guide: `lncshared` Git ownership

## Confirmation

In TIKEASY and UPIMO, `lncshared` is configured as a real Git submodule.

Evidence in TIKEASY:

```text
.gitmodules exists
git submodule status shows lncshared
git ls-files --stage lncshared shows mode 160000
```

Evidence in UPIMO:

```text
.gitmodules exists
git submodule status shows:
1f0b3e3ee72a5d972628b6ac8c2c6339d7efae31 lncshared (heads/master)
git ls-files --stage lncshared shows:
160000 1f0b3e3ee72a5d972628b6ac8c2c6339d7efae31 0 lncshared
```

Mode `160000` means the parent project stores only a Git commit pointer for `lncshared`, not the full file tree.

In kView INVESTOR, `lncshared` is currently not configured like TIKEASY.

Evidence in kView INVESTOR:

```text
.gitmodules does not exist
git submodule status is empty
git ls-files --stage lncshared/... shows normal file mode 100644
```

Mode `100644` means the parent kView INVESTOR repository tracks each `lncshared` file directly.

There is also a stale/broken `lncshared/.git` file:

```text
lncshared/.git -> gitdir: ../.git/modules/lncshared
```

But the corresponding submodule metadata is not active in the parent repository. In practice, kView INVESTOR is in a hybrid state:

- the parent repo tracks `lncshared` files directly;
- `lncshared/.git` suggests it used to be, or was intended to be, a submodule;
- Git does not currently treat it as a proper submodule.

## Project comparison

| Project | `.gitmodules` | `git submodule status` | `lncshared` tracked as | Status |
| --- | --- | --- | --- | --- |
| TIKEASY | Yes | Shows `lncshared` | Gitlink mode `160000` | Correct submodule setup |
| UPIMO | Yes | Shows `lncshared` at `1f0b3e3...` | Gitlink mode `160000` | Correct submodule setup |
| kView INVESTOR | No | Empty | Normal files mode `100644` | Not a proper submodule |

So UPIMO confirms the same intended architecture as TIKEASY: `lncshared` should be owned and committed in the `lncshared` repository, while the application repository commits only the submodule pointer.

## Why this matters

Shared code changes made under `lncshared/` in kView INVESTOR are currently recorded as normal kView INVESTOR changes.

That means a commit in kView INVESTOR can accidentally include shared-library changes such as:

```text
lncshared/app/Models/DynamicField.php
lncshared/app/Http/Resources/DynamicResource.php
lncshared/app/Exceptions/...
```

This is not the TIKEASY pattern.

In the TIKEASY pattern:

1. shared code is committed inside the `lncshared` repository;
2. the application repository commits only the updated submodule pointer;
3. other applications can choose when to update to the new shared commit.

## Current risk in kView INVESTOR

Because kView INVESTOR tracks `lncshared` files directly:

- shared fixes can become kView INVESTOR-only;
- TIKEASY and other projects will not receive them automatically;
- future updates from the real `lncshared` repository may conflict with the vendored copy;
- reviewing a kView INVESTOR commit becomes noisy because application code and shared-library code are mixed;
- the stale `.git` pointer can mislead developers into thinking `lncshared` is already a submodule.

## Recommended target state

kView INVESTOR should match TIKEASY:

```text
kview_investor/
  .gitmodules
  lncshared/    -> Git submodule pointing to git@bitbucket.org:lnconsulting/lncshared.git
```

The parent repository should track `lncshared` as a single gitlink entry:

```text
160000 <commit> lncshared
```

It should not track individual files like:

```text
100644 ... lncshared/app/Models/DynamicField.php
```

## Migration plan

Do not run this blindly on a dirty worktree. First preserve all current kView INVESTOR changes, especially changes under `lncshared/`.

### 1. List current shared changes

From the kView INVESTOR root:

```powershell
git status --short -- lncshared
git diff -- lncshared
```

Current known modified shared files include:

```text
lncshared/app/Exceptions/DuplicateCompositePrimaryKeyException.php
lncshared/app/Exceptions/DuplicateDynamicFieldException.php
lncshared/app/Exceptions/StrictModeException.php
lncshared/app/Http/Resources/DynamicResource.php
lncshared/app/Models/DynamicField.php
lncshared/app/Models/DynamicModel.php
lncshared/resources/assets/js/components/forms/input-dropdown.vue
```

These changes must be reviewed and moved into the real `lncshared` repository if they are shared-library changes.

### 2. Commit or patch shared changes in `lncshared`

Apply the relevant changes to a clean checkout of:

```text
git@bitbucket.org:lnconsulting/lncshared.git
```

Then commit them in the `lncshared` repository.

Example:

```powershell
git clone git@bitbucket.org:lnconsulting/lncshared.git C:\dev.cloud\lncshared-work
```

Copy/reapply the selected shared changes, then:

```powershell
git -C C:\dev.cloud\lncshared-work status
git -C C:\dev.cloud\lncshared-work add .
git -C C:\dev.cloud\lncshared-work commit -m "Update dynamic fields and dropdown support"
git -C C:\dev.cloud\lncshared-work push
```

### 3. Remove vendored `lncshared` files from kView INVESTOR index

Only after the shared changes are safe in the real `lncshared` repo:

```powershell
git -C C:\dev.cloud\kview_investor rm -r --cached lncshared
```

This removes `lncshared` files from the kView INVESTOR index without deleting the working tree copy.

Depending on the broken/stale `.git` state, it may be cleaner to move the folder away temporarily:

```powershell
Move-Item C:\dev.cloud\kview_investor\lncshared C:\dev.cloud\kview_investor\lncshared.backup
```

### 4. Add `lncshared` as a real submodule

```powershell
git -C C:\dev.cloud\kview_investor submodule add git@bitbucket.org:lnconsulting/lncshared.git lncshared
```

Then check out the commit that contains the needed shared changes:

```powershell
git -C C:\dev.cloud\kview_investor\lncshared checkout <shared_commit_sha>
```

### 5. Commit the submodule pointer in kView INVESTOR

The kView INVESTOR commit should include:

```text
.gitmodules
lncshared
```

where `lncshared` is a gitlink, not a directory of normal tracked files.

Verify:

```powershell
git -C C:\dev.cloud\kview_investor ls-files --stage lncshared
```

Expected:

```text
160000 <commit> 0 lncshared
```

Then:

```powershell
git -C C:\dev.cloud\kview_investor add .gitmodules lncshared
git -C C:\dev.cloud\kview_investor commit -m "Use lncshared as a submodule"
```

## What not to do

Do not simply commit `lncshared/app/...` files in kView INVESTOR.

That preserves the current problem: kView INVESTOR keeps a private copy of shared code.

Do not delete the current `lncshared` folder before extracting the current changes.

There are active shared-code changes in the working tree that may need to be migrated.

Do not trust the presence of `lncshared/.git`.

In kView INVESTOR it currently points to submodule metadata, but the parent repository is not actually configured as a submodule.

## Short conclusion

Yes: kView INVESTOR should be updated to use `lncshared` as a submodule like TIKEASY and UPIMO.

Before doing that, the current shared-code modifications in kView INVESTOR must be reviewed and committed to the real `lncshared` repository. Then kView INVESTOR should commit only the updated submodule pointer.